App architecture

A Beignet app keeps production code in a small set of predictable places, and each folder owns one kind of decision. This page is the map: what lives where, where each production concern goes, and the dependency direction beignet lint enforces. For the first-hour loop, use Quickstart; for the guided tour of one feature, use Build your first feature.

What goes where

The CLI starter scaffolds the subset of this structure it ships: contracts, schemas, routes, use cases, components, ports, infra, server composition, and the client. Workflow-tier artifacts such as jobs, listeners, notifications, schedules, uploads, the outbox registry, and operational tasks appear when beignet make generators add them, along with their lib/ builders and server registries. beignet doctor treats their absence as fine and their misplacement as drift.

Production concern map

When you know what you need to build, this table says where it goes:

Dependency direction

The rule is simple: transport, application behavior, and infrastructure do not own each other. A feature owns its contracts, route group, use cases, policy, domain model, UI, and feature-specific ports. App-wide ports describe dependencies shared across features. Infra implements those ports. Domain concepts that are genuinely shared across features live in features/shared/domain/.

beignet lint enforces the most important directions. Domain and use cases cannot import infra, UI, route, client, provider, or framework code. Feature domain cannot import another feature's domain unless it comes from features/shared/domain. Route files cannot import infra or UI, and infra adapters cannot import UI, routes, server modules, or clients. Contract files and everything reachable from client/ or "use client" modules are also checked as client-safe import graphs that must not reach server-only code; see the CLI reference for the full lint rules.

Two placement notes that follow from the rule:

• Small feature-root helper modules are allowed — for example a features/issues/history.ts with pure helpers shared across the feature's use cases. Keep them pure: as soon as a helper needs a dependency, give it a port.
• Test placement follows ownership: feature behavior tests live in features/<feature>/tests/, while infra and server modules may keep adjacent *.test.ts files beside the module they exercise, such as a repository test next to its adapter.

Feature-owned UI

Product UI lives with the feature it serves, in features/<feature>/components/. Shared client wiring — the typed Beignet client, React Query helper, React Hook Form helper, upload client, and QueryClient provider — lives in client/. Feature components import those helpers plus their feature's contracts, and call endpoints through React Query and form adapters.

components/ may contain React Server Components and Client Components. Server Components can call server-only modules when they are not reachable from a client root. Client Components and anything they import cannot reach use cases, route groups, infra adapters, server modules, provider packages, or app-context.ts — keep server-only workflows behind route groups and explicit server entrypoints. See React for the component patterns.

Server composition

Features keep route wiring local in features/<feature>/routes.ts, and the server composes them at the boundary: server/routes.ts owns the central route list, server/context.ts declares the context blueprint once for the runtime and route tests, server/index.ts assembles ports, providers, hooks, and routes, and a catch-all app/api/[[...path]]/route.ts exposes server.api. That convention gives the CLI one source of truth for route inspection, generation, OpenAPI wiring, and drift checks. The code for each piece is on Routes and server.

Custom paths

Use beignet.config.ts when your app keeps the same architecture under different paths:

import { defineConfig } from "@beignet/cli/config";

export default defineConfig({
  paths: {
    contracts: "src/features",
    features: "src/features",
    routes: "src/app/api",
    server: "src/core/server/index.ts",
  },
});

Config changes where the CLI looks and writes. It does not replace the architecture: feature contracts still define the HTTP boundary, the server still registers route groups, and application code still belongs behind use cases and ports.