47 lines
1.7 KiB
Markdown
47 lines
1.7 KiB
Markdown
|
# Architecture overview
|
||
|
|
|
||
|
|
Descrybe v2 is a **Go chi API + SvelteKit web + PostgreSQL** rewrite (no Clerk).
|
||
|
|
|
||
|
|
## Runtime processes
|
||
|
|
|
||
|
|
| Process | Role |
|
||
|
|
|---------|------|
|
||
|
|
| apps/api/cmd/api | HTTP API (sessions, CSRF, public /api/v1, admin) |
|
||
|
|
| apps/api/cmd/worker | Processing jobs, Woo/Shopify claim, support AI auto jobs, billing cycles |
|
||
|
|
| apps/web | SvelteKit 2 / Svelte 5 UI (Vite proxies /api to API) |
|
||
|
|
| PostgreSQL 16 | System of record (goose migrations under apps/api/sql/schema) |
|
||
|
|
|
||
|
|
`npm run dev` starts API + web. **Worker is separate** — without it, process jobs and many background syncs stall.
|
||
|
|
|
||
|
|
## Component diagram
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
flowchart LR
|
||
|
|
Browser["Browser :28472"] --> Web["SvelteKit apps/web"]
|
||
|
|
Web -->|"/api proxy"| API["Go chi API :28471"]
|
||
|
|
API --> PG[(PostgreSQL)]
|
||
|
|
Worker["cmd/worker"] --> PG
|
||
|
|
API -->|"NOTIFY processing_jobs"| Worker
|
||
|
|
Worker -->|"ClaimNext SKIP LOCKED"| PG
|
||
|
|
Ext["OpenAI / Woo / Shopify / Stripe / SMTP"] -.-> API
|
||
|
|
Ext -.-> Worker
|
||
|
|
```
|
||
|
|
|
||
|
|
## Auth surfaces
|
||
|
|
|
||
|
|
- **Dashboard session:** cookie + CSRF (X-CSRF-Token) under /api/*
|
||
|
|
- **Public API key:** Bearer or X-API-Key under /api/v1 (no CSRF)
|
||
|
|
- **Public tokens:** /api/public/* (export feeds CSV/XML, unsubscribe, brand logos)
|
||
|
|
- **Platform admin:** /api/admin/* after RequirePlatformAdmin (support desk subset for support_staff)
|
||
|
|
|
||
|
|
## Key packages
|
||
|
|
|
||
|
|
- internal/httpapi — routes + middleware
|
||
|
|
- internal/processing — product description jobs
|
||
|
|
- internal/feeds / woocommerce / shopify — ingest and connectors
|
||
|
|
- internal/support — tickets, KB, FAQ/AI auto-reply
|
||
|
|
- internal/billing — plans, credits, Stripe
|
||
|
|
- internal/jobs — enqueue processing (Postgres pending + NOTIFY; River client deferred)
|
||
|
|
|
||
|
|
Sources: README.md, apps/api/internal/httpapi/server.go, apps/api/cmd/worker/main.go.
|