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

# Structure

> The directory layout and generated files of an Ooneex module — definition, config, package, tests, and artifact folders.

A module is a self-contained unit of your application that lives under `modules/<name>/`. Running [`ooneex module:create`](/module/create) scaffolds a fixed set of files: a definition that lists the module's artifacts, a config file, a workspace `package.json`, a `tsconfig.json`, and a mirrored test. Everything you generate afterward — controllers, entities, services, middleware — lands in predictable subfolders under `src/`. This page walks through that layout file by file.

See [Overview](/module/overview) for what a module is and [Composition](/module/composition) for how modules combine.

## Layout

A freshly created `billing` module looks like this:

```text theme={null}
modules/billing/
├── billing.yml                    # module config (type)
├── package.json                   # workspace package: @module/billing
├── tsconfig.json                  # TypeScript config
├── src/
│   ├── BillingModule.ts           # module definition (ModuleType)
│   ├── controllers/               # @decorator.controller() classes
│   ├── services/                  # injectable services
│   ├── repositories/              # data-access repositories
│   ├── entities/                  # database entities
│   └── middlewares/               # IMiddleware / ISocketMiddleware classes
├── tests/
│   └── BillingModule.spec.ts      # asserts the ModuleType arrays exist
└── bin/                           # optional: seeds and runnable commands
```

The artifact subfolders under `src/` (`controllers/`, `services/`, `repositories/`, `entities/`, `middlewares/`) are created on demand as you generate artifacts into the module — a new module starts with just `src/<Pascal>Module.ts`. The `bin/` folder is optional and holds seeds and runnable commands for modules that need them.

## Generated files

### `src/<Pascal>Module.ts` — the module definition

The heart of the module. It exports a single `ModuleType` object whose arrays declare what the module contributes to the application. You register each artifact you create by adding it to the matching array.

```typescript theme={null}
import type { ModuleType } from "@ooneex/module";

export const BillingModule: ModuleType = {
  controllers: [],
  entities: [],
  middlewares: [],
  cronJobs: [],
  events: [],
};
```

Each array maps to a kind of artifact and the `src/` subfolder where those artifacts live:

| `ModuleType` array | Artifact                     | Lives under               |
| ------------------ | ---------------------------- | ------------------------- |
| `controllers`      | HTTP / WebSocket controllers | `src/controllers/`        |
| `entities`         | Database entities            | `src/entities/`           |
| `middlewares`      | Request middleware           | `src/middlewares/`        |
| `cronJobs`         | Scheduled jobs               | `src/` (cron job classes) |
| `events`           | Event listeners              | `src/` (event classes)    |

Services and repositories are dependency-injected and resolved through the container, so they live under `src/services/` and `src/repositories/` without a dedicated `ModuleType` array. See [Controller](/components/controller) and [Entity](/components/entity) for those artifact types, and [Middleware](/basics/middleware) for the middleware pipeline.

### `<name>.yml` — module config

Declares the module's type. The generator writes `type: "module"`:

```yaml theme={null}
type: "module"
```

The `type` is one of `api`, `microservice`, `design`, `spa`, `sdk`, or `module`, depending on what kind of unit you scaffold.

### `package.json` — workspace package

Each module is its own workspace package named `@module/<name>`. It starts at version `0.0.1` and ships `test` and `lint` scripts:

```json theme={null}
{
  "name": "@module/billing",
  "version": "0.0.1",
  "scripts": {
    "test": "bun test tests",
    "lint": "..."
  }
}
```

The `@module/billing` package name doubles as the import-path alias once it is registered in the root `tsconfig.json` (see [Registration](#registration)).

### `tsconfig.json`

The module's TypeScript configuration, extending the workspace defaults.

### `tests/<Pascal>Module.spec.ts` — the mirrored test

Every module ships a test that mirrors the definition and asserts each `ModuleType` array exists. It guards against a malformed definition — checking that `controllers`, `entities`, `middlewares`, `cronJobs`, and `events` are all present on the exported module object. Run it with the package's `test` script (`bun test tests`).

## Core modules: `app` and `shared`

Two modules are special and exist in every project:

| Module   | Role                                                                                                                                                                                            |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app`    | The application root. It composes the other modules and is the default destination for generated artifacts that belong to the running app.                                                      |
| `shared` | Cross-cutting code reused across modules — shared services, middleware, and utilities. It is the default target for several generators (for example, `middleware:create` defaults to `shared`). |

When you create a module with the `app` destination, the generator registers it into both `AppModule` and `SharedModule` so its artifacts are wired into the application and available to other modules.

## Registration

Creating a module is not just file generation — `module:create` also wires the module into the project:

* **Registers the module** into its destination. For the `app` destination, it adds the module to `AppModule` and `SharedModule`.
* **Adds the path alias.** The `@module/<name>` import alias is added to the root `tsconfig.json`, so other code can import the module by its package name.
* **Adds the commit scope.** When a `.commitlintrc.ts` is present, the module's scope is added so commits can be scoped to the module.

## Next steps

* [Overview](/module/overview) — what a module is and why modules exist.
* [Composition](/module/composition) — how modules are combined into an application.
* [Create](/module/create) — the `module:create` command reference.
* [Controller](/components/controller) and [Entity](/components/entity) — the artifacts you register in the definition.
* [Middleware](/basics/middleware) — the request pipeline a module contributes to.