asepharyana
3882c5aef0
- Introduced AGENT-SPECS.md detailing the specifications for seven agents including their inputs, processing steps, and outputs. - Created API-REFERENCE.md outlining the Sectors API v2 endpoints, parameters, costs, and usage. - Developed API.md to specify backend routes, request/response structures, and error handling. - Established ARCHITECTURE.md to describe the project layout, conventions, scheduler, and citation pipeline. - Added DATA-MODEL.md to define the database schema, tables, and seed strategy. - Compiled PLAN.md to outline the project concept, problem statement, unique features, and implementation timeline. - Created README.md as an index for documentation with links to all relevant files. - Documented ROUTINES.md detailing the seven automated routines, their schedules, inputs, detection logic, and delivery formats. - Introduced TECH-STACK.md to specify the technology choices and rationale for both backend and frontend components.
4.4 KiB
4.4 KiB
Tech stack
Pinned versions. Change here before code. CI enforces the gates at the bottom.
Backend — backend/ (Go 1.23)
| Piece | Choice | Why |
|---|---|---|
| Runtime | Go 1.23 | Single binary, fast cold start on demo machines, net/http routing mature since 1.22 |
| Router | chi v5 | Thin router over stdlib mux (middleware, route groups); no framework lock-in |
| HTTP client | stdlib net/http + tuned Transport |
One shared client for all Sectors calls (pooling, per-endpoint timeouts) |
| Validation | go-playground/validator v10 | Request struct tags = kontrak docs/API.md; gagal validasi → 422 |
| DB | database/sql + modernc.org/sqlite (pure Go) |
Nol CGO — mattn/go-sqlite3 butuh gcc dan gagal di mesin juri tanpa toolchain; schema Postgres-compatible, migrasi SQL polos bernomor, tanpa ORM |
| Cache | go-redis v9; in-memory TTL fallback bila REDIS_URL kosong |
Cache registry/taxonomy (TTL 24 jam); demo tetap jalan tanpa Redis |
| Scheduler | robfig/cron v3 | Cron per routine + interval ingestion dalam satu proses |
| LLM | Plain HTTPS ke endpoint OpenAI-compatible (LLM_BASE_URL) |
Function calling untuk synthesis/report/briefing; LLM_MODEL_TRIAGE murah + LLM_MODEL_SYNTH kuat, override lewat env |
| PDF export | gofpdf (jung-kurt fork) | Pure Go, tanpa system deps |
| Config | env via os.Getenv + godotenv untuk dev |
Semua secret dari env; contoh di .env.example |
| Test | go test + httptest (mock upstream Sectors) |
Agent/rule/budget tests atas fixture JSON bentuk API asli |
| Lint/type | gofmt -l + go vet ./... (+ golangci-lint bila tersedia) |
Compiler sudah strict; vet menangkap yang penting |
Frontend — web/ (SolidJS + StyleX)
| Piece | Choice | Why |
|---|---|---|
| Framework | SolidJS 1.9 + Vite 6 + TypeScript 5.6 | Fine-grained reactivity — ideal untuk live feed/SSE tanpa re-render tree; bundle kecil untuk demo cepat |
| Styling | StyleX (@stylexjs/stylex + @stylexjs/vite-plugin) | Atomic CSS deterministic, typed via TS, tanpa runtime; ganti Tailwind sepenuhnya |
| Charts | Chart.js 4 via solid-chartjs | Wrapper Solid resmi untuk flow/series; Recharts React-only jadi tidak dipakai |
| Data fetch | fetch + typed client (lib/api.ts) + EventSource untuk SSE |
Backend satu-satunya sumber kebenaran; web tidak pernah manggil Sectors langsung |
| Test/gate | tsc --noEmit + vite build |
Cukup untuk hackathon; tanpa e2e framework |
Package / runtime management
| Piece | Choice | Why |
|---|---|---|
| Go deps | Go modules (go.mod, vendoring opsional via go mod vendor) |
Build reproducible; go build ./... satu perintah |
| JS deps | pnpm 9 + pnpm-lock.yaml |
Install deterministik; fallback npm jika pnpm tidak ada |
| Env | .env (tidak di-commit) — SECTORS_API_KEY, LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_SYNTH, LLM_MODEL_TRIAGE, TELEGRAM_BOT_TOKEN, DISCORD_WEBHOOK_URL, REDIS_URL |
Semua secret dari env; contoh di .env.example |
| Procfile dev | dua proses: go run ./cmd/server (atau air untuk reload) + vite dev (+ redis opsional) |
Demo tetap jalan tanpa Redis |
Alternatives declined
- Python/FastAPI — startup + packaging demo lebih rapuh (venv, pip) dibanding satu binary Go; konkurensi agent paralel setara via goroutine.
- Next.js/React — overhead framework + re-render model untuk dashboard live; Solid memberi update granular dengan bundle lebih kecil.
- Tailwind — diganti StyleX: atomic, typed, nol runtime, tanpa scanning step.
- Recharts — React-only; Chart.js via solid-chartjs menutup kebutuhan chart di Solid.
- mattn/go-sqlite3 — butuh CGO/gcc; modernc pure-Go selalu bisa build.
- GORM / sqlc / Alembic-style migrator — overhead untuk 13 tabel; SQL polos + skrip bernomor cukup dan mudah diaudit juri.
- Celery / job queue eksternal — butuh broker; cron in-process cukup untuk siklus 30 menit.
- WebSocket — push satu arah saja (agents/alerts/activity); SSE lebih simpel + auto-reconnect.
- tRPC / GraphQL — REST + JSON typed tanpa layer tambahan.
- MongoDB — data relasional time-series (ticker × date); SQLite + indeks tepat lebih cepat dibangun.
CI gates (per commit)
gofmt -l backend/kosong +go vet ./...bersihgo test ./...(termasuk budget test: kredit per siklus ≤ cap pada fixture)tsc --noEmit+vite builddiweb/- Larangan: tidak ada HTTP call ke
api.sectors.appdi luarbackend/sectors/; tidak ada angka user-visible tanpa citation (review checklist, bukan linter).