Architecture

Two deployables, one repo, one contract between them.

Why two deployables

The frontend and the backend scale, fail and deploy for different reasons. A publishing worker retrying LinkedIn's API has nothing to do with a marketing lead loading a chart. Splitting them means the API can be scaled, restarted or rewritten without touching the UI, and the UI can be served from an edge without dragging a database driver along. See DECISIONLOG.md D-001.

The seam is enforced, not merely documented:

Repository layout

Request lifecycle

POST /api/v1/auth/login
  → cors()                     app.ts                 separate origins, so CORS is mandatory
  → limit("login", 10)         http/middleware.ts     per-IP fixed window, Postgres-backed
  → body(c, loginSchema)       @verjson/contracts     the same schema the web app validated with
  → domain logic               modules/auth/routes.ts
  → prisma                     core/db.ts             the single ORM touch-point
  → sUser(user)                core/serializers.ts    camelCase row → snake_case JSON
  ← 200 { user, tokens }
  (any throw)                  → http/error-handler.ts → { detail } + status

No route handler contains a try/catch. Throw ApiError(status, message) and the single app.onError hook shapes the response — which is why the error format cannot drift between endpoints.

Conventions

Backend modules

Present today; the rest land as features are built — see FEATURES.md.

Frontend areas

Provider adapters

Every external platform implements one interface, so adding a channel is one file plus a registry entry — no change to the publisher, the inbox, or analytics.

ChannelProvider
  getAuthUrl(redirectUri, state)            → string
  exchangeCode(code, redirectUri)           → OAuthTokens
  refreshToken(refreshToken)                → OAuthTokens
  getProfile(token)                         → AccountProfile
  publish(token, content)                   → PublishResult
  getPostMetrics(token, postId)             → PostMetrics
  getAccountMetrics(token, range)           → AccountMetrics
  getMessages(token, since)                 → InboxMessage[]
  reply(token, messageId, text)             → ReplyResult
  revoke(token)                             → boolean

  readonly platform: Platform
  readonly maxCaptionLength: number
  readonly supportedPostTypes: PostType[]
  readonly rateLimits: RateLimitConfig

Ad platforms implement a second interface, AdsProvider, because their verbs are different — budgets, bids, conversion actions, benchmarks — not posts.

Background work

Publishing, metric collection and token refresh are scheduled, not request-driven. They run as a separate process from the same image as the API, calling the same core/ functions — which is exactly why core/ may not import Hono.

Deployment

Both images are multi-stage and run unprivileged. The API's readiness probe is its own /api/v1/health, which reports 503 when Postgres is unreachable so the orchestrator routes around an unhealthy pod rather than serving errors from it.

See DEPLOYMENT.md.