App architecture

A Beignet app keeps production code in a small set of predictable places. Each folder owns one kind of decision.

app/api/
app-context.ts
client/
domain/      optional shared kernel
features/
infra/
lib/
ports/
server/

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. Top-level domain/ is only for concepts that are genuinely shared across features.

beignet lint enforces the most important dependency direction rules: domain and use cases cannot import infra, UI, route, client, provider, or framework code; route files cannot import infra or UI; and provider packages stay behind ports and infra adapters.

Route registration

Beignet apps keep route wiring close to the feature and compose route groups at the server boundary:

// features/todos/routes.ts
import { defineRouteGroup } from "@beignet/next";
import type { AppContext } from "@/app-context";
import * as contracts from "@/features/todos/contracts";
import { listTodosUseCase } from "@/features/todos/use-cases";

export const todoRoutes = defineRouteGroup<AppContext>({
  name: "todos",
  routes: [
    {
      contract: contracts.listTodos,
      handle: async ({ ctx, query }) => ({
        status: 200,
        body: await listTodosUseCase.run({ ctx, input: query }),
      }),
    },
  ],
});

Then server/routes.ts owns the central route list:

import { contractsFromRoutes, defineRoutes } from "@beignet/next";
import type { AppContext } from "@/app-context";
import { todoRoutes } from "@/features/todos/routes";

export const routes = defineRoutes<AppContext>([todoRoutes]);
export const contracts = contractsFromRoutes(routes);

And server/index.ts becomes app composition:

import { createNextServer } from "@beignet/next";
import { createAnonymousActor } from "@beignet/core/ports";
import { appPorts } from "@/infra/app-ports";
import type { AppContext } from "@/app-context";
import { routes } from "./routes";

export const server = await createNextServer<AppContext, typeof appPorts>({
  ports: appPorts,
  createContext: ({ ports }) => ({
    actor: createAnonymousActor(),
    requestId: crypto.randomUUID(),
    ports,
  }),
  routes,
});

Then a catch-all Next.js route file exposes the central handler:

// app/api/[[...path]]/route.ts
import { server } from "@/server";

export const DELETE = server.api;
export const GET = server.api;
export const HEAD = server.api;
export const OPTIONS = server.api;
export const PATCH = server.api;
export const POST = server.api;
export const PUT = server.api;

That convention keeps features responsible for their HTTP wiring while giving the CLI one source of truth for route inspection, resource generation, OpenAPI wiring, and drift checks.

Production concern map

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.