Project Structure

WHERE THE LAYOUT COMES FROM

Zudo does not force a folder layout on you. Nothing in @zudojs/core reads a directory or looks for a file by name — you can put your code anywhere.

What does have an opinion is the CLI. When you run zudo create, it writes one of three layouts, and the rest of the CLI (generate, dev, add) expects that layout afterwards.

Choose with --architecture, or answer the prompt:

MONOLITH LAYOUT

This is what zudo create my-api -p pnpm produces. The files with a comment hold working code; every other folder under src/ contains only an empty index.ts, a place ready for your own code.

There is no zudojs.config.ts and no zudo.config.ts. See The Files at the Root for where the project’s settings live.

HOW A REQUEST FLOWS

Follow one request, GET /api/v1/examples, through the files above. Each layer has one job and only talks to the layer below it:

src/server.ts is the file npm run dev runs. It loads the configuration, builds the router, registers every route, and puts three middlewares in front of it. A middleware is a step every request passes through:

src/routes/index.ts is where every route is registered. /health is always first; generated resources go between the markers:

src/container.ts is the composition root: the one place each controller is built with its service, and each service with its repository. To swap the in-memory repository for a database one, you change one line here and nothing else:

src/app.ts assembles the runtime, the part that starts and stops modules in order: the integrations first, then AppModule and any module you generate. On Ctrl+C (SIGINT) or SIGTERM, server.ts lets integrations close long-lived connections, stops HTTP, then stops the runtime.

The routes the new project answers:

CONFIGURATION AND .ENV

Settings that differ between your laptop and production (ports, URLs, passwords) are read from environment variables, never written into the code. .env.example lists every variable the app reads. Copy it to .env (which git ignores) and edit the copy:

src/configs/index.ts loads .env when it exists (real environment variables win), reads each value through @zudojs/config, and returns one frozen, typed object. A bad value stops the app at start-up with a clear error, for example PORT must be an integer between 0 and 65535.

zudo add <feature> adds its own variables to .env.example and its settings to src/configs/index.ts, for example REDIS_URL and redis: { url }.

INTEGRATIONS

An integration is a connection to something outside your code, such as Redis, a database, a WebSocket server or an email service, that has to be opened when the app starts and closed when it stops. src/integrations/ is where they live. A new project has none yet, only the contract each one follows:

zudo add redis writes src/integrations/redis.ts and appends it to the list in src/integrations/index.ts. Integrations start in list order before every other module and stop in reverse after them, and each one’s health shows up in /health under checks.

THE ZUDOJS MARKERS

You have seen comments like these in the snippets above:

Each pair fences a list that the CLI appends to. generate and add only ever insert lines between a :start and its :end, and skip a line that is already there. Everything outside the markers is yours to edit freely, and so are the lines between them.

WHAT EACH FOLDER HOLDS

The folders are a convention, not a rule — but the CLI's generate command writes into them by these names, so it pays to keep them.

THE FILES AT THE ROOT

The scripts and the zudojs block a monolith gets:

MODULAR MONOLITH LAYOUT

The same single app, with the same files and folders as a monolith — plus one folder per module under src/modules/. Each module owns its own commands/, queries/ and routes/.

Without --services you get no modules, just an empty src/modules/index.ts. Name the modules you want:

Commands and queries are the two halves of a common split: a command changes something, a query only reads. Keeping them in separate folders makes it obvious at a glance which code can alter data.

Add another module later without touching the rest. It is registered in app.ts and its routes in src/routes/index.ts:

To give a module its own endpoint, add --module to generate resource. The layers go inside the module and the routes are registered in its routes/index.ts:

MICROSERVICE LAYOUT

Here the project is a workspace: one repository holding several apps that install and deploy separately. A gateway app sits in front on port 3000, and each service gets its own port from 3001 up. Every app is wired exactly like a monolith: its own server.ts, router, container.ts, configuration, example resource and tests.

Without --services you get the gateway and nothing under apps/services/. Each app has its own package.json and its own dependencies. The root package.json only fans commands out across them — its dev script runs every app's dev script.

With pnpm the workspace members are listed in pnpm-workspace.yaml; with npm, yarn or bun they are a workspaces array in the root package.json. Either way the globs are the same:

A microservice project is created with a Dockerfile per app and a docker-compose.yml that runs the whole set with docker compose up. Other architectures get Docker files from zudo add docker.

To work on one app, pass --service: zudo generate resource invoices --service billing writes into apps/services/billing/, and zudo add redis --service billing adds Redis to that app only. Without it, generate writes into apps/gateway/ and add applies to every app.

WHERE GENERATE PUTS FILES

zudo generate <kind> <name> reads the architecture from your project first, then picks the folders and registers what it wrote. Add --dry-run to see the paths without writing anything. A controller needs a service, repository and DTO to compile, so the missing ones come with it:

The fourteen kinds, and where each lands in a monolith:

Two flags change the destination:

• --module <name> puts the files inside src/modules/<name>/ instead of the shared folders. It is ignored for generate module itself.
• --service <name> picks the app in a microservice project (apps/services/<name>/; without it, apps/gateway/), and names the owner of a command or query elsewhere.

NAMING CONVENTIONS

Every generated file says what it is in its own name: <name>.<kind>.ts, lower-case and hyphenated. The exported class is the PascalCase version with the kind appended. camelCase input keeps its word boundaries.

A name is a name, not a path: /, \ and .. are refused, and so is a name starting with a digit (it would not be a valid class name).

Two more conventions worth keeping:

• Every folder has an index.ts barrel you can use to re-export its contents. Generated resources do not rely on them: container.ts and routes/index.ts import each file directly.
• Relative imports end in .js, never .ts. The generated tsconfig.json uses "module": "Node16", which requires the extension of the file that will exist after compiling.

NEXT STEPS

• • Architecture — why the framework is split this way.
• • Module System — how modules are registered, ordered and loaded.
• • zudojs-cli — the full command and flag reference.
• • Package Rules — the conventions the framework's own 39 packages follow.