Architecture

FRAME is founded on a unidirectional monorepo model managed by pnpm Workspaces and Turborepo. This structure enables a clear separation of concerns and a predictable dependency flow.

Workspace Organization

FRAME is divided into applications, shared packages, configs, and a scaffolding CLI.

Applications (Apps)

App	Role
apps/next	Main web product. Next.js App Router + Tailwind CSS v4 + shadcn/ui.
apps/nest	Backend API and services with NestJS.
apps/astro	Starlight portal with Tailwind CSS v4 (product documentation / static content).
docs/	Monorepo documentation site (Starlight + Tailwind CSS v4). Do not confuse with apps/astro.

Packages

Package	Technical Responsibility
models	Drizzle schemas and Zod DTOs on PostgreSQL.
core	Agnostic utilities, Zod config, and shared pure logic.
events	Integration event contracts typed with Zod.
auth	Authentication SDK with Better Auth.
mail	Templates and SMTP transport with React Email.
cli	CLI (frame setup, process-scoped secret injection, and environment loading).

Other

Path	Role
configs/*	Shared presets (oxlint, tsconfig).
create/	create-frame generator for derived monorepos.

Dependency Flow Diagram

graph TD
    subgraph Packages
        M[models]
        C[core]
        E[events]
        Ma[mail]
        A[auth]
    end

    subgraph Apps
        NEXT[next]
        NEST[nest]
        ASTRO[astro]
        DOCS[docs site]
    end

    NEXT --> M
    NEXT --> C
    NEXT --> A
    NEST --> M
    NEST --> C
    NEST --> E
    NEST --> Ma
    NEST --> A
    ASTRO --> C
    DOCS --> C

Engineering Standards

[!IMPORTANT] Ban on any: All code must be strictly typed. If a structure is unknown, it must be defined in the appropriate place.

• Styling by surface:
  • (apps/next): Tailwind CSS v4 + shadcn/ui. CSS Modules only for complex layout.
  • apps/astro: Tailwind CSS v4.
  • docs/: CSS/SCSS (this docs site only).
• Validation: inputs and outputs validated with Zod on frontend and backend.
• Internal scaffolding: Turbo Gen (pnpm gen), not Plop CLI.

Internal Architectures

• Next.js: App Router, proxy.ts as the sole middleware, routes under app/[locale]/**, runtime under src/.
• NestJS: modules, controllers, services, pipes, and Zod validation.
• Astro / docs: Starlight pages and components; React islands when interactivity is needed.