# evcat6/balancy-app-backend architecture

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

- Interactive diagram: https://gitdiagram.com/evcat6/balancy-app-backend
- Repository: https://github.com/evcat6/balancy-app-backend

## Overview

##### Project type and purpose
- This is a full-stack application’s backend, implemented with the NestJS framework.
- It exposes REST endpoints for user management, authentication, tasks, and sub-categories, relies on a relational database (via TypeORM entities), and integrates external services (Google OAuth, email).

##### File structure
- Top-level src/app.module.ts registers all modules: Auth, Users, Tasks, SubCategories, Common, Config.
- Each module follows Nest’s pattern: `<module>.controller.ts` (HTTP entry point), `<module>.service.ts` (business logic), plus DTOs and Entity definitions under `/dto` and `/entities`.
- Common folder holds cross-cutting concerns: decorators, guards (roles, JWT), and utility services (email, logger).
- Config module loads environment variables (config-validation-schema, configuration.ts).
- Authentication uses Passport with Local, JWT, and Google strategies.

##### README for additional insights
- The app runs in dev/prod modes, supports unit & e2e testing.

##### Main components and their interactions
a. Clients
– Web or mobile clients (e.g., React/Vue, Postman) issue HTTP requests.
b. API Gateway (NestJS host)
– main.ts bootstraps the Nest application, applies global pipes (validation), exception filters if any.
1. Auth Module
- Controllers: auth.controller.ts – login, change-password, OAuth callbacks.
- Guards & Strategies: LocalAuthGuard, JwtAuthGuard, GoogleStrategy, JwtStrategy.
- Service: issues JWTs, interfaces with Users service.
2. Users Module
- Controllers: users.controller.ts – CRUD on users.
- Service: user management, password hashing.
- Entities/DTOs: mapping to DB.
3. Tasks Module
- Controllers & Service for task CRUD.
- Entities: task.entity.ts.
- Types: response interfaces.
4. SubCategories Module
- Similar to Tasks: controllers, service, entity.
5. Common Module
- Cross-cutting: logger, email service, role-based guards, custom decorators (@Public, @Roles, @User).
6. Config Module
- Loads and validates environment variables (database credentials, JWT secret, OAuth client IDs).
d. Database
– A relational DB (PostgreSQL/MySQL) accessed via TypeORM (entity classes under each module).
e. External Services
– Google OAuth endpoint
– Email provider (SMTP or transactional service)

##### Architectural patterns and design principles
- Layered architecture: Presentation (controllers), Business (services), Data (entities/repositories).
- Modular decomposition: each feature in its own module with clear boundaries.
- Dependency injection: all services injected via Nest’s DI container.
- Cross-cutting concerns handled by Common module (guards, decorators).
- Configuration isolation via Config module.

##### Detail
- Call out global pipes/guards on the API boundary.
- Config module feeding secrets/config into modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients["Web/Mobile Clients\n(Postman)"]:::external

    %% API Gateway
    subgraph "NestJS API Gateway" 
        direction TB
        Main["main.ts\n(bootstrap)"]:::api
        AppModule["app.module.ts\n(root module)"]:::api

        %% Auth Module
        subgraph "Auth Module" 
            direction TB
            AuthModule["auth.module.ts"]:::api
            AuthController["auth.controller.ts"]:::api
            AuthService["auth.service.ts"]:::api
            AuthDTOs["DTOs"]:::api
            LocalGuard["local-auth.guard.ts"]:::api
            JwtGuard["jwt-auth.guard.ts"]:::api
            GoogleStrategy["google.strategy.ts"]:::api
            JwtStrategy["jwt.strategy.ts"]:::api
            LocalStrategy["local.strategy.ts"]:::api
        end

        %% Users Module
        subgraph "Users Module" 
            direction TB
            UsersModule["users.module.ts"]:::api
            UsersController["users.controller.ts"]:::api
            UsersService["users.service.ts"]:::api
            UsersDTOs["DTOs"]:::api
            UserEntity["user.entity.ts"]:::api
        end

        %% Tasks Module
        subgraph "Tasks Module"
            direction TB
            TasksModule["tasks.module.ts"]:::api
            TasksController["tasks.controller.ts"]:::api
            TasksService["tasks.service.ts"]:::api
            TasksDTOs["DTOs"]:::api
            TaskEntity["task.entity.ts"]:::api
            TaskTypes["types-response.interface.ts"]:::api
        end

        %% SubCategories Module
        subgraph "SubCategories Module"
            direction TB
            SubCatModule["sub-categories.module.ts"]:::api
            SubCatController["sub-categories.controller.ts"]:::api
            SubCatService["sub-categories.service.ts"]:::api
            SubCatDTOs["DTOs"]:::api
            SubCatEntity["sub-category.entity.ts"]:::api
        end

        %% Common Module
        subgraph "Common Module"
            direction TB
            Decorators["decorators"]:::api
            CommonGuards["guards"]:::api
            EmailService["email.service.ts"]:::api
            LoggerService["logger.service.ts"]:::api
        end

        %% Config Module
        subgraph "Config Module"
            direction TB
            ValidationSchema["config-validation-schema.ts"]:::api
            Configuration["configuration.ts"]:::api
            ConfigIndex["index.ts"]:::api
        end

        %% Application Service
        AppService["app.service.ts"]:::api
    end

    %% Database
    Database["Relational DB\n(PostgreSQL/MySQL)"]:::db

    %% External Services
    GoogleOAuth["Google OAuth API"]:::externalService
    EmailProvider["SMTP/Email Provider"]:::externalService

    %% Connections
    Clients -->|"HTTP"| Main
    Main --> AppModule
    AppModule --> AuthModule
    AppModule --> UsersModule
    AppModule --> TasksModule
    AppModule --> SubCatModule
    AppModule --> Decorators
    AppModule --> ValidationSchema

    AuthModule --> AuthController
    AuthController --> AuthService
    AuthService --> UsersService
    AuthService -->|"JWT"| JwtGuard
    AuthService -->|"Local"| LocalGuard
    AuthService --> GoogleStrategy
    AuthService --> JwtStrategy
    AuthService --> LocalStrategy
    AuthService -->|"HTTP"| GoogleOAuth

    UsersModule --> UsersController
    UsersController --> UsersService
    UsersService --> UserEntity
    UsersService --> Database

    TasksModule --> TasksController
    TasksController --> TasksService
    TasksService --> TaskEntity
    TasksService --> TaskTypes
    TasksService --> Database

    SubCatModule --> SubCatController
    SubCatController --> SubCatService
    SubCatService --> SubCatEntity
    SubCatService --> Database

    Decorators --> CommonGuards
    CommonGuards --> JwtGuard
    CommonGuards --> LocalGuard
    TasksService --> EmailService
    UsersService --> EmailService
    EmailService -->|"SMTP"| EmailProvider

    Configuration --> AppModule
    ValidationSchema --> Configuration

    AppModule --> AppService

    %% Click Events
    click Main "https://github.com/evcat6/balancy-app-backend/blob/development/src/main.ts"
    click AppModule "https://github.com/evcat6/balancy-app-backend/blob/development/src/app.module.ts"

    click AuthModule "https://github.com/evcat6/balancy-app-backend/blob/development/src/auth/auth.module.ts"
    click AuthController "https://github.com/evcat6/balancy-app-backend/blob/development/src/auth/auth.controller.ts"
    click AuthService "https://github.com/evcat6/balancy-app-backend/blob/development/src/auth/auth.service.ts"
    click AuthDTOs "https://github.com/evcat6/balancy-app-backend/tree/development/src/auth/dto"
    click LocalGuard "https://github.com/evcat6/balancy-app-backend/blob/development/src/auth/local-auth.guard.ts"
    click JwtGuard "https://github.com/evcat6/balancy-app-backend/blob/development/src/auth/jwt-auth.guard.ts"
    click GoogleStrategy "https://github.com/evcat6/balancy-app-backend/blob/development/src/auth/strategies/google.strategy.ts"
    click JwtStrategy "https://github.com/evcat6/balancy-app-backend/blob/development/src/auth/strategies/jwt.strategy.ts"
    click LocalStrategy "https://github.com/evcat6/balancy-app-backend/blob/development/src/auth/strategies/local.strategy.ts"

    click UsersModule "https://github.com/evcat6/balancy-app-backend/blob/development/src/users/users.module.ts"
    click UsersController "https://github.com/evcat6/balancy-app-backend/blob/development/src/users/users.controller.ts"
    click UsersService "https://github.com/evcat6/balancy-app-backend/blob/development/src/users/users.service.ts"
    click UsersDTOs "https://github.com/evcat6/balancy-app-backend/tree/development/src/users/dto"
    click UserEntity "https://github.com/evcat6/balancy-app-backend/blob/development/src/users/entities/user.entity.ts"

    click TasksModule "https://github.com/evcat6/balancy-app-backend/blob/development/src/tasks/tasks.module.ts"
    click TasksController "https://github.com/evcat6/balancy-app-backend/blob/development/src/tasks/tasks.controller.ts"
    click TasksService "https://github.com/evcat6/balancy-app-backend/blob/development/src/tasks/tasks.service.ts"
    click TasksDTOs "https://github.com/evcat6/balancy-app-backend/tree/development/src/tasks/dto"
    click TaskEntity "https://github.com/evcat6/balancy-app-backend/blob/development/src/tasks/entities/task.entity.ts"
    click TaskTypes "https://github.com/evcat6/balancy-app-backend/blob/development/src/tasks/types/types-response.interface.ts"

    click SubCatModule "https://github.com/evcat6/balancy-app-backend/blob/development/src/sub-categories/sub-categories.module.ts"
    click SubCatController "https://github.com/evcat6/balancy-app-backend/blob/development/src/sub-categories/sub-categories.controller.ts"
    click SubCatService "https://github.com/evcat6/balancy-app-backend/blob/development/src/sub-categories/sub-categories.service.ts"
    click SubCatDTOs "https://github.com/evcat6/balancy-app-backend/tree/development/src/sub-categories/dto"
    click SubCatEntity "https://github.com/evcat6/balancy-app-backend/blob/development/src/sub-categories/entities/sub-category.entity.ts"

    click Decorators "https://github.com/evcat6/balancy-app-backend/tree/development/src/common/decorators"
    click CommonGuards "https://github.com/evcat6/balancy-app-backend/tree/development/src/common/guards"
    click EmailService "https://github.com/evcat6/balancy-app-backend/blob/development/src/common/services/email.service.ts"
    click LoggerService "https://github.com/evcat6/balancy-app-backend/blob/development/src/common/services/logger.service.ts"

    click ValidationSchema "https://github.com/evcat6/balancy-app-backend/blob/development/src/config/config-validation-schema.ts"
    click Configuration "https://github.com/evcat6/balancy-app-backend/blob/development/src/config/configuration.ts"
    click ConfigIndex "https://github.com/evcat6/balancy-app-backend/blob/development/src/config/index.ts"
    click AppService "https://github.com/evcat6/balancy-app-backend/blob/development/src/app.service.ts"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef api fill:#98FB98,stroke:#333,stroke-width:1px
    classDef db fill:#FFA500,stroke:#333,stroke-width:1px
    classDef externalService fill:#87CEFA,stroke:#333,stroke-width:1px
```
