> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> DealerOS application architecture, tenancy model, authentication, data model, configuration, and deployment topology.

# Architecture Overview

DealerOS is a multi-tenant SaaS for automotive dealer groups: vehicle inventory, a public marketplace with listings and lead capture, CRM leads, self-serve signup and onboarding, Stripe-backed billing, and a provider abstraction layer for third-party automotive integrations.

## System overview

| | |
| - | - |
| Live web console | `https://app.dealeros.pndsvcs.com` |
| Live API | `https://api.dealeros.pndsvcs.com` |
| Repository | `PcnaidInc/Pcnaid-Dealer-Lifecycle-OS` |
| Workspace | Nx 22 + pnpm 9.15.4 workspaces (`apps/*`, `packages/*`) |
| API | NestJS 11 on `@nestjs/platform-express`, Node 24, ESM |
| Web | Next.js 15 App Router, React 19, server components + server actions |
| Data | Managed PostgreSQL, accessed through `pg` (Pool) — no ORM |
| Tenancy | PostgreSQL FORCE ROW LEVEL SECURITY on every table in schema `app` |
| Identity | Auth0 (organizations, authorization-code + PKCE web login, RS256 JWT/JWKS) |
| Billing | Stripe Checkout + Billing Portal + signature-verified webhook |
| Media | Azure Blob Storage (private containers, short-lived SAS read URLs) |
| Hosting | Two containerized services (API and web), each built from its own Dockerfile |

## Runtime applications

* **Web** (`apps/web`): Next.js App Router console and responsive public marketing site. Handles Auth0 authorization-code login, callback, logout, encrypted/signed HTTP-only session cookie, and console surfaces: organization, inventory, marketplace, leads, providers, onboarding, billing, signup, and public listing pages.
* **API** (`apps/api`): NestJS API, default-deny behind a global guard. Provides session/tenant resolution, organization, inventory, marketplace, media, leads, signup, invitations, onboarding, billing, providers, and signature-verified Stripe/Resend/provider webhooks.
* **End-to-end tests** (`apps/web-e2e`): Playwright specs plus local Auth0 and Stripe-compatible mocks, including the complete signup, trial, onboarding, and invite journey.

The web server calls the API from `apps/web/src/lib/dealeros-api.ts`. Authenticated calls attach an Auth0 access token and the selected tenant UUID. Public marketplace calls omit those headers.

## Request flow

```text theme={null}
browser
  → Cloudflare DNS (app.dealeros.pndsvcs.com)
  → Web service (Next.js)                        [encrypted+signed HttpOnly session cookie]
       → server component / server action
       → fetch https://api.dealeros.pndsvcs.com     [Authorization: Bearer <Auth0 access token>]
                                                      [x-dealeros-tenant-id: <uuid>]
         → API service (NestJS)
           → AuthenticatedTenantGuard (APP_GUARD, default-deny)
             → Auth0JwtService (Auth0 JWKS/RS256)
             → TenantResolverService (membership lookup in Postgres)
           → module service
             → DatabaseService.withTenant(...)
               → Postgres under FORCE RLS
```

## Authentication and tenant isolation

The API registers `AuthenticatedTenantGuard` as a global application guard. Unless a controller or handler is marked public, a request must provide:

* `Authorization: Bearer <auth0-access-token>`
* `x-dealeros-tenant-id: <tenant-uuid>`

Tenant resolution checks that the token's Auth0 organization matches an active DealerOS tenant and that the subject has an active membership. A user without a previously verified email is rejected.

Database work runs inside a transaction that calls `app.set_tenant_context` before executing tenant queries. SQL migrations enable and force row-level security across tenant-owned tables. Runtime connections are reset with `DISCARD ALL` before returning to the pool.

## Shared packages

* `packages/config`: validates runtime configuration with Zod
* `packages/db`: PostgreSQL pooling, tenant transaction context, migration execution
* `packages/design-tokens`: generates the theme consumed by the marketing build
* `packages/shared`: request schemas and shared domain records
* `packages/provider-framework`: provider registration, capability, rights, credential-reference, and idempotency contracts

## Data model

The repository contains 19 ordered SQL migration files (`0001_foundation.sql` through `0019_credential_refs_are_references.sql`). Major table groups include:

* **Tenancy and delivery**: tenants, identities, memberships, audit log, outbox, webhook inbox, sent email, idempotency records
* **Inventory**: vehicle identities, vehicles, builds, VIN snapshots, inventory units
* **Marketplace**: media assets, dealer settings, vehicle offers, listings, revisions, search documents, saved searches, favorites
* **CRM**: leads, routing rules, lead status events
* **Providers**: catalog, entitlements, routes, circuit breakers, webhook inbox, usage events
* **Self-service**: plan tiers, billing accounts, invitations, onboarding progress, signup requests, feature overrides, signup claims

Migrations are plain SQL, applied in lexical order, recorded in `app.schema_migrations`, and wrapped one file at a time in a transaction.

## Configuration

`packages/config/src/index.ts` groups configuration for application URLs and release, Auth0, Turnstile, billing, PostgreSQL, email, media storage, marketplace search, observability, providers, Temporal, and Cloudflare switches. The implementation defaults marketplace search to PostgreSQL and local media storage. Azure Blob storage is supported when selected and configured.

## Web route map

| Surface | Routes |
| - | - |
| Marketing artifacts | `/`, `/platform`, `/pricing`, `/security`, `/contact` |
| Account entry | `/login`, `/signup/dealership`, `/verify-email`, `/invite/accept`, `/select-organization` |
| Console | authenticated `/`, `/organization`, `/billing`, `/onboarding`, `/inventory`, `/inventory/[id]`, `/marketplace`, `/leads`, `/providers` |
| Public marketplace | `/public/marketplace`, `/public/marketplace/[slug]` |
| Trust and legal | `/trust`, `/legal/accessibility`, `/legal/cookies`, `/legal/disclosures`, `/legal/privacy`, `/legal/terms` |

## Deployment topology

The repository contains separate multi-stage Dockerfiles for the API and web application. Runtime images expose ports `4000` (API) and `3000` (web) and run as a non-root `dealeros` user. The infrastructure manifests describe two container services, an image build, and health checks for both services. Production media is configured for Azure Blob storage; marketplace search uses PostgreSQL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.