# 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.