Architecture
One portal, one API, one PostgreSQL database. Everything else is optional by construction.
A Frontstead Kit deployment uses one public portal frontend, one API, and one PostgreSQL database. PostgreSQL is the system of record and the only required data service.
Browser | vapps/portal (Next.js, default public frontend) | | HTTP / same-origin API proxy vapps/api (Express + Prisma) --------------+----------------+ | | | v v vPostgreSQL (required) Redis (optional) Typesense (optional) ^ |apps/mls-service (included, separate worker) ^ |MLS/RESO provider (optional credentials)Components
| Component | Responsibility | Required |
|---|---|---|
apps/portal |
Public pages, property search and details, inquiries, consumer auth, favorites | Yes |
apps/api |
REST API, authentication, portal operations, optional Agent API | Yes |
| PostgreSQL | Authoritative application, account, listing, and sync data | Yes |
apps/mls-service |
Persistent MLS ingestion and synchronization worker | Included; runs when MLS is configured |
| Typesense | Optional search acceleration | No |
| Redis | Optional caching integration | No |
Commercial and deployment-specific frontends are maintained in separate repositories. They consume the versioned HTTP API and are not part of the public core deployment.
Request and data flow
Anonymous portal calls use the portal's same-origin /api rewrite.
Authenticated consumer calls go through a portal server route that reads an httpOnly session cookie and forwards the JWT to the API as a Bearer token. Browser JavaScript never needs direct access to the raw session token — the exchange happens server-side.
The API reaches PostgreSQL through Prisma. Property search and the API search fallback use PostgreSQL ILIKE/trigram behaviour. When TYPESENSE_HOST is configured, selected search paths may use Typesense and fall back to PostgreSQL on failure.
Typesense never replaces PostgreSQL's authority. It produces candidates; PostgreSQL decides what is true.
The MLS worker is deliberately separate
apps/mls-service is operated separately from request-serving processes. It writes normalized MLS data and sync state to the same PostgreSQL database, and it can start without synchronization credentials and simply remain idle.
Do not sync licensed data into a publicly reachable deployment until board approval and every public read path have been verified. See Display compliance.
Packages
db/ Prisma schema, migrations, generated client, guarded demo seedsapi-client/ Shared API base URL resolution and client contractsportal-config/ Portal policy and configurationsearch/ PostgreSQL search fallback and optional Typesense integrationcache/ Optional Redis integrationemail/ Transactional email supporttokens/ Shared design tokensui/ Shared UI primitives@frontstead/tokens, @frontstead/ui, and @frontstead/api-client are published to npm under Apache-2.0, so you can consume the design system and API contracts without adopting the monorepo.
Environment boundaries
The services do not share an environment. That is a deliberate deployment property, and it is worth internalizing before you configure anything:
- Portal —
NEXT_PUBLIC_API_URLpoints at the API; the local fallback ishttp://localhost:3001. - API —
DATABASE_URL,JWT_SECRET, and portal origin settings.FRONTEND_URLidentifies the portal origin, not a legacy web runtime or a slug route. - MLS worker — its own service environment, sharing only the database and intentionally matching MLS board identifiers with the API.
- Omit optional Typesense variables when it is absent. Set
REDIS_ENABLED=falsewhen Redis is absent.
Agent API boundary
/api/agent/* routes fail closed. Only an operator integrating a compatible external client should set AGENT_API_ENABLED=true; every checked-in example uses false. See Agent API.
What this document is
This describes implemented architecture, not intentions. Proposed transport, service, or package changes live in scoped GitHub issues until they ship.