# zera-app/nest-11-starter architecture

> Architecture diagram of the GitHub repository zera-app/nest-11-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zera-app/nest-11-starter
- Repository: https://github.com/zera-app/nest-11-starter

## Overview

##### Project Type & Purpose
- This is a NestJS-based TypeScript starter monorepo project. It is structured as a full-stack application with two distinct apps—a backend and a client—each following modular approaches.
- The purpose is to provide a foundation for building scalable server-side applications. Standard NestJS concepts such as modules, controllers, services, pipes, and guards are utilized for authentication and other business logic.

##### Analyzing the File Structure
- Top-level directories:
- apps: Contains two main applications (“backend” and “client”). Both apps have independent source directories, controllers, modules, services, and tests.
- libs: Divides common functionalities into multiple modules such as “common” (decorators, guards, pipes, responses), “repositories” (database models and repositories), and “utils” (helper functions for date, encryption, string manipulation, etc.).
- prisma: Handles database migrations and seeding using Prisma with migration files and seeders for roles and users.
- mails: Contains email templates (e.g., for authentication verification, forgot password) that are used by the mail service.
- Configuration files (.env.example, nest-cli.json, tsconfig files, etc.) that support building, testing, and linting.
- The structure demonstrates clear separation of concerns following modular design, which is common in NestJS projects.

##### Key Architectural Components
a. Main Applications:
- Backend Application:
- Houses authentication (auth module, controllers, and services), main entry (main.ts), and testing.
- Client Application:
- Contains client-specific modules and authentication similar to the backend but may serve a different purpose (UI layering or a distinct API logic).

b. Shared Libraries (in the libs directory):
- Common Module:
- Contains decorators, guards, pipes, and standardized response formats.
- Repositories:
- Manages database models for users, roles, tokens (access, reset), email verification.
- Utils:
- Provides utility functions for encryption, hashing, date formatting, and more.
- BullMQ Integration (in libs/common/src/bullmq):
- Likely used for background jobs such as sending emails or token cleanup.

c. Database & ORM:
- Prisma:
- Represents the database schema, migration history, and seed scripts. It is central to persist user data, authentication tokens, and more.

d. Email Service:
- Mails Directory:
- Holds Handlebars templates for sending emails related to authentication (email verification, reset password).

e. CI/CD & Deployment:
- GitHub workflows (.github/workflows) and deployment scripts indicate continuous integration practices.
- Instructions in the README and the mention of an external deployment platform (Mau) for cloud deployment of NestJS apps.

##### Relationships & Interactions
- The Backend application interacts with:
- The common libraries for shared features like authentication guards or decorators.
- The repositories library to access and manipulate database entities via Prisma.
- The utilities library for encryption, hashing, and common operations.
- The mail service (in libs/common/mail) to send templated emails using contents from the mails folder.
- The Client application, although structured similarly, could provide frontend API endpoints or alternative interactions with the backend services.
- Both apps may share authentication logic from their “auth” modules, and they depend on shared libraries for standardized business logic.
- CI/CD components (GitHub workflows) ensure regular builds/deployments and integration with external deployment services like Mau.
- The Prisma layer sits at the center for persistent data, with migration scripts and seeders ensuring database integrity.

##### Architectural Patterns & Principles
- Modular architecture: Each app is broken down into modules (e.g., auth, client) and shares code through libraries.
- Separation of concerns: Business logic (services), HTTP handling (controllers), and database interactions (repositories) are separated.
- Reusability: Shared functionalities are encapsulated within libs (common, utils, repositories).
- Scalability: The split between backend and client applications allows independent scaling and evolution as needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Applications Subgraph
    subgraph "Applications"
        BA["Backend Application"]:::app
        CA["Client Application"]:::app
    end

    %% Shared Libraries Subgraph
    subgraph "Shared Libraries"
        CL["Common Library"]:::shared
        subgraph "Common Modules"
            MM["Mail Module"]:::shared
            BMQ["BullMQ Integration"]:::shared
        end
        RL["Repositories Library"]:::shared
        UL["Utils Library"]:::shared
    end

    %% Other Components
    DB["Database (Prisma)"]:::db
    ET["Email Templates"]:::shared
    CICD["CI/CD & Deployment"]:::external

    %% Relationships
    BA -->|"uses"| CL
    BA -->|"accesses"| RL
    BA -->|"utilizes"| UL
    CA -->|"uses"| CL
    CA -->|"accesses"| RL
    CA -->|"utilizes"| UL
    CL -->|"includes"| MM
    CL -->|"includes"| BMQ
    MM -->|"sends"| ET
    RL -->|"manages"| DB
    BA -->|"triggers"| MM
    BA -->|"calls"| BMQ
    CICD -->|"builds_deploys"| BA
    CICD -->|"builds_deploys"| CA

    %% Click Events
    click BA "https://github.com/zera-app/nest-11-starter/tree/main/apps/backend"
    click CA "https://github.com/zera-app/nest-11-starter/tree/main/apps/client"
    click CL "https://github.com/zera-app/nest-11-starter/tree/main/libs/common"
    click BMQ "https://github.com/zera-app/nest-11-starter/blob/main/libs/common/src/bullmq/bullmq.module.ts"
    click RL "https://github.com/zera-app/nest-11-starter/tree/main/libs/repositories"
    click UL "https://github.com/zera-app/nest-11-starter/tree/main/libs/utils"
    click DB "https://github.com/zera-app/nest-11-starter/tree/main/prisma"
    click ET "https://github.com/zera-app/nest-11-starter/tree/main/mails"
    click CICD "https://github.com/zera-app/nest-11-starter/tree/main/.github/workflows"

    %% Styles
    classDef app fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef shared fill:#FFF2CC,stroke:#333,stroke-width:2px;
    classDef db fill:#C7E9C0,stroke:#333,stroke-width:2px;
    classDef external fill:#F7CE5B,stroke:#333,stroke-width:2px;
```
