# Cedar CMS (Backend Monolith)

## 🏁 Getting Started

### Prerequisites

-   Node.js >= 22.18.0
-   npm or yarn
-   PostgreSQL instance

### Installation

1.  Clone the repository:
    ```bash
    git clone <repository-url>
    cd cedar-api
    ```

2.  Install dependencies:
    ```bash
    yarn install
    ```

3.  Set up environment variables:
    Create a `.env` file in the root directory (refer to `.env.example` if available, otherwise configure your DB connection details).

4.  Setup the database with the codebase's schema:
    > Note: Run `yarn prisma:migrate` every time you make changes to the Prisma schema.
    ```bash
    yarn prisma:push
    ```

5.  Generate Prisma Client:
    > Note: Run this command every time you make changes to the Prisma schema.
    ```bash
    yarn prisma:generate
    ```

6.  Start the development server:
    ```bash
    yarn dev
    ```

### Available Scripts

-   `yarn dev`: Start the development server with hot-reloading (using `tsx`).
-   `yarn build`: Build the project for production.
-   `yarn start`: Start the production server.
-   `yarn lint`: Lint the codebase using Biome.
-   `yarn format`: Format the codebase using Biome.
-   `yarn test`: Run unit tests using Vitest.
-   `yarn coverage`: Run tests with coverage reporting.
-   `yarn prisma:push`: Pushes the state of the Prisma schema to the database without migrations.
-   `yarn prisma:migrate`: Creates a new migration while reruning the existing migration history. (use for development only)
-   `yarn prisma:generate`: Generates the Prisma Client with updated schema.

## 🧪 Testing

The project uses **Vitest** for unit and integration testing.

### Running Tests

```bash
# Run all tests
yarn test

# Run tests with coverage
yarn coverage
```

### Test Structure

Tests are **co-located** with the source code they test. This keeps tests close to the implementation and makes it easier to maintain.

-   **File Naming**: `*.spec.ts`
-   **Location**: Same directory as the source file (e.g., `src/modules/users/domain/users.entity.ts` -> `src/modules/users/domain/users.entity.spec.ts`).

### Writing Tests

We use **Vitest** as our test runner, which provides a Jest-compatible API.

1.  **Domain Entities**: Test business logic and invariants within entities.
    -   *Example*: `src/modules/users/domain/users.entity.spec.ts`
2.  **Use Cases**: Test application logic by mocking dependencies (Repositories, Services) using `vi.fn()` or `vi.spyOn()`.
    -   *Example*: `src/modules/auth/use-cases/login-user.spec.ts`
3.  **Shared Infrastructure**: Test generic implementations (fakes) to ensure they behave correctly.
    -   *Example*: `src/shared/infrastructure/persistence/fakes/InMemoryRepository.spec.ts`

## API Documentation

The project uses **Swagger UI** to visualize and interact with the API's resources.

### Accessing Swagger UI

Start the development server (`yarn dev`) and navigate to:
`http://localhost:3000/docs`

This endpoint will only be available if the env var `ENVIRONMENT` is not `production`.

### Defining Routes

We use `swagger-jsdoc` to generate the OpenAPI specification from JSDoc comments directly in the route files.

**Example:**

```typescript
/**
 * @openapi
 * /hello-world:
 *  get:
 *    tags:
 *      - Hello World
 *    summary: Greet the user
 *    responses:
 *      200:
 *        description: Success
 *        content:
 *          text/plain:
 *            schema:
 *              type: string
 */
router.get("/", (req, res) => {
  res.send("Hello world!");
});
```

## 📂 Project Structure

The project is organized into modules and shared components. For a detailed deep-dive into the architecture, please refer to [ARCHITECTURE.md](./ARCHITECTURE.md).

```
src/
├── modules/           # Feature-specific modules (e.g., users, auth)
│   └── users/
│       ├── domain/    # Entities & Repository Interfaces
│       ├── use-cases/ # Application Business Rules
│       └── infrastructure/ # DB, HTTP, DI implementations
├── shared/            # Shared kernel, base classes, utilities
│   ├── core/
│   └── infrastructure/
└── app.ts             # Application entry point
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

This project is licensed under the MIT License.