Portal

Browser-facing app for the mktco stack.

Owns

• Better Auth sign-in and sign-up
• protected chat UI
• same-origin portal API routes
• server-side gateway JWT minting
• preview/live site management UI
• mandatory portal-owned Gitea account provisioning and account helpers
• startup-time validation of mandatory Better Auth, gateway, and Gitea config

Core boundary

Browser -> Portal -> Gateway

The browser talks to portal routes only. Gateway JWTs and shared secrets stay server-side.

Main surfaces

• /{locale}/auth — public auth screen
• /{locale}/chat — protected chat screen
• app/api/** — same-origin routes that proxy or orchestrate backend work

Key directories

• app/ — routes, layouts, and route handlers
• components/ — UI composition and client hooks
• lib/ — auth, gateway, site, and mandatory Gitea logic
• docs/ — stable package-level docs
• scripts/ — runtime helpers and migrations

Product rules

• one active run in the UI model
• there is one logical chat/session per user workspace
• the portal may keep a best-effort local cached transcript per browser/user for UX resilience, but that cache is not a separate session model
• preview means the editable workspace's built dist/ output
• live means a separate checkout deployed from committed workspace state
• SITE_HOSTING_MODE stays explicit: disabled, local, or managed
• in local mode, preview/live are inspected through repo helper commands rather than direct public links

Local commands

npm run dev
npm run typecheck
npm run build
npm start

Portal startup validates mandatory Better Auth, gateway, and Gitea configuration before serving requests. Temporary Gitea outages are handled at request time; only missing or placeholder config blocks startup.

Current Gitea setup is manual:

• GITEA_ADMIN_TOKEN must come from an admin-capable Gitea account that can create users, create repos, reset passwords, and delete users
• GITEA_SYNC_SERVICE_USERNAME names the separate sync account that portal adds as a collaborator on each provisioned workspace repo
• GITEA_PASSWORD_SECRET is a required portal secret used to encrypt stored pending Gitea passwords
• the portal does not create either of these accounts or tokens for you

npm run provision:user-site -- alice

From the repo root (site:preview serves the workspace dist/ output, site:live serves the live checkout dist/ output):

npm run site:preview -- alice
npm run site:live -- alice

Package docs

• docs/overview.md — scope and boundaries
• docs/auth-and-gateway.md — auth flow and portal->gateway contract
• docs/ui.md — chat and website-management UI scope

Related packages

• gateway contract: ../gateway/README.md
• deployment/operator docs: ../cli/README.md and ../cli/docs/