151 lines
4.3 KiB
Markdown
151 lines
4.3 KiB
Markdown
# 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.
|