# scvapp/scvappbackend architecture

> Architecture diagram of the GitHub repository scvapp/scvappbackend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scvapp/scvappbackend
- Repository: https://github.com/scvapp/scvappbackend

## Overview

##### Project type and purpose
- This is a monolithic, full-stack backend service built on NestJS (TypeScript) that manages lockers, door access passes, notifications, authentication, and administrative functions for a school or facility.
- Key use cases include: user authentication/authorization, opening/locking lockers, creating door passes, logging door events, real-time updates via WebSockets, and sending notifications to registered devices.

##### File structure
- src/ contains domain modules:
- auth (login, JWT, guards)
- user (profile, schedules)
- admin (school/class configuration)
- lockers (locker entities, controllers, WebSocket gateway)
- pass (door pass entities, pass gateway, logging)
- notification (API-key middleware, device registry, sending pushes)
- search (search across entities)
- token (token DTOs/service for refresh/verification)
- config/ and .env.example hold environment settings and deploy.yml for CI/CD.
- SCVApp/ holds Bruno runtime scripts or use-case specifications.
- db_migrations/ contains SQL for stored procedures.
- test/ holds unit and e2e tests.
- Dockerfile, .kamal hooks, and nest-cli.json point to containerized deployment and Nest CLI usage.

##### README for additional insights
- Confirms use of NestJS modules, TypeScript, and standard Nest application structure.

##### Recommendations
- Be exhaustive: include all eight modules plus config/CI artifacts.
- Data flow in two scenarios: synchronous HTTP calls (e.g., openLocker) and asynchronous real-time events (socket push).
- Use layering: Presentation (Clients), Application (Controllers + Gateways), Domain (Services + Entities), Infrastructure (Database, External APIs), Deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients"
        direction TB
        WebClient["Web Client"]:::external
        MobileClient["Mobile Client"]:::external
    end

    %% NestJS Application
    subgraph "NestJS Server"
        direction TB

        %% HTTP Controllers
        subgraph "HTTP Controllers"
            direction TB
            AuthController["AuthController"]:::http
            UserController["UserController"]:::http
            AdminController["AdminController"]:::http
            LockersController["LockersController"]:::http
            PassController["PassController"]:::http
            NotificationController["NotificationController"]:::http
            SearchController["SearchController"]:::http
        end

        %% WebSocket Gateways
        subgraph "WebSocket Gateways"
            direction TB
            LockersGateway["LockersGateway"]:::ws
            PassGateway["PassGateway"]:::ws
        end

        %% Services
        subgraph "Services"
            direction TB
            AuthService["AuthService"]:::service
            UserService["UserService"]:::service
            AdminService["AdminService"]:::service
            LockersService["LockersService"]:::service
            PassService["PassService"]:::service
            NotificationService["NotificationService"]:::service
            SearchService["SearchService"]:::service
            TokenService["TokenService"]:::service
        end

        %% Entities (Database Models)
        subgraph "Entities"
            direction TB
            LockerEntity["Locker Entities"]:::entity
            PassEntity["Door Pass Entities"]:::entity
            NotificationEntities["Notification Entities"]:::entity
            TokenDTOs["Token DTOs"]:::entity
        end

    end

    %% Database
    Database["Relational Database"]:::database

    %% External Services
    PushService["Push Notification Provider"]:::external
    MessageBroker["Optional Message Broker"]:::external

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        Workflow["GitHub Actions (deploy.yml)"]:::ci
        DeployConfig["Deployment Config"]:::ci
        KamalHooks["Kamal Hooks"]:::ci
        Docker["Docker Container"]:::ci
    end

    %% Connections: HTTP
    WebClient -->|HTTP| AuthController
    MobileClient -->|HTTP| AuthController

    AuthController -->|"uses"| AuthService
    UserController -->|"uses"| UserService
    AdminController -->|"uses"| AdminService
    LockersController -->|"uses"| LockersService
    PassController -->|"uses"| PassService
    NotificationController -->|"uses"| NotificationService
    SearchController -->|"uses"| SearchService

    %% WebSocket
    WebClient -->|WebSocket| LockersGateway
    MobileClient -->|WebSocket| LockersGateway
    WebClient -->|WebSocket| PassGateway
    MobileClient -->|WebSocket| PassGateway

    LockersGateway -->|"real-time"| LockersService
    PassGateway -->|"real-time"| PassService

    %% Services to Entities & DB
    AuthService -->|"CRUD"| Database
    UserService -->|"CRUD"| Database
    AdminService -->|"CRUD"| Database
    LockersService -->|"CRUD"| Database
    PassService -->|"CRUD"| Database
    NotificationService -->|"CRUD"| Database
    SearchService -->|"CRUD"| Database
    TokenService -->|"CRUD"| Database

    %% Entities map to DB
    LockerEntity --> Database
    PassEntity --> Database
    NotificationEntities --> Database
    TokenDTOs --> Database

    %% Notification external call
    NotificationService -->|HTTP| PushService

    %% Optional broker
    LockersGateway -->|PUB/SUB| MessageBroker
    PassGateway -->|PUB/SUB| MessageBroker
    NotificationService -->|SUBSCRIBE| MessageBroker

    %% CI/CD flow
    Workflow --> DeployConfig
    DeployConfig --> Docker
    Docker --> KamalHooks

    %% Click Events
    click AuthController "https://github.com/scvapp/scvappbackend/blob/master/src/auth/auth.controller.ts"
    click AuthService "https://github.com/scvapp/scvappbackend/blob/master/src/auth/auth.service.ts"
    click AuthModule "https://github.com/scvapp/scvappbackend/blob/master/src/auth/auth.module.ts"
    click UserController "https://github.com/scvapp/scvappbackend/blob/master/src/user/user.controller.ts"
    click UserService "https://github.com/scvapp/scvappbackend/blob/master/src/user/user.service.ts"
    click UserModule "https://github.com/scvapp/scvappbackend/blob/master/src/user/user.module.ts"
    click AdminController "https://github.com/scvapp/scvappbackend/blob/master/src/admin/admin.controller.ts"
    click AdminService "https://github.com/scvapp/scvappbackend/blob/master/src/admin/admin.service.ts"
    click AdminModule "https://github.com/scvapp/scvappbackend/blob/master/src/admin/admin.module.ts"
    click LockersController "https://github.com/scvapp/scvappbackend/blob/master/src/lockers/lockers.controller.ts"
    click LockersService "https://github.com/scvapp/scvappbackend/blob/master/src/lockers/lockers.service.ts"
    click LockersGateway "https://github.com/scvapp/scvappbackend/blob/master/src/lockers/lockers.gateway.ts"
    click LockersModule "https://github.com/scvapp/scvappbackend/blob/master/src/lockers/lockers.module.ts"
    click LockerEntity "https://github.com/scvapp/scvappbackend/blob/master/src/lockers/entities/locker.entity.ts"
    click PassController "https://github.com/scvapp/scvappbackend/blob/master/src/pass/pass.controller.ts"
    click PassService "https://github.com/scvapp/scvappbackend/blob/master/src/pass/service/pass.service.ts"
    click PassGateway "https://github.com/scvapp/scvappbackend/blob/master/src/pass/pass.gateway.ts"
    click PassModule "https://github.com/scvapp/scvappbackend/blob/master/src/pass/pass.module.ts"
    click PassEntity "https://github.com/scvapp/scvappbackend/blob/master/src/pass/entities/doorPass.entity.ts"
    click NotificationController "https://github.com/scvapp/scvappbackend/blob/master/src/notification/notification.controller.ts"
    click NotificationService "https://github.com/scvapp/scvappbackend/blob/master/src/notification/notification.service.ts"
    click NotificationModule "https://github.com/scvapp/scvappbackend/blob/master/src/notification/notification.module.ts"
    click NotificationEntities "https://github.com/scvapp/scvappbackend/blob/master/src/notification/entities/apiKey.entity.ts"
    click SearchController "https://github.com/scvapp/scvappbackend/blob/master/src/search/search.controller.ts"
    click SearchService "https://github.com/scvapp/scvappbackend/blob/master/src/search/search.service.ts"
    click SearchModule "https://github.com/scvapp/scvappbackend/blob/master/src/search/search.module.ts"
    click TokenService "https://github.com/scvapp/scvappbackend/blob/master/src/token/token.service.ts"
    click TokenDTOs "https://github.com/scvapp/scvappbackend/blob/master/src/token/token.dto.ts"
    click TokenModule "https://github.com/scvapp/scvappbackend/blob/master/src/token/token.module.ts"
    click Database "https://github.com/scvapp/scvappbackend/blob/master/db_migrations/locker_function.sql"
    click SCVApp "https://github.com/scvapp/scvappbackend/tree/master/SCVApp/"
    click Workflow "https://github.com/scvapp/scvappbackend/blob/master/.github/workflows/deploy.yml"
    click DeployConfig "https://github.com/scvapp/scvappbackend/blob/master/config/deploy.yml"
    click KamalHooks "https://github.com/scvapp/scvappbackend/tree/master/.kamal/hooks/sample"
    
    %% Styles
    classDef http fill:#D0E8FF,stroke:#005B99,color:#000
    classDef ws fill:#DFFFE0,stroke:#339900,color:#000
    classDef service fill:#FFF4D0,stroke:#D2A106,color:#000
    classDef entity fill:#FFE0E0,stroke:#D10000,color:#000
    classDef database fill:#FFEFD5,stroke:#FF8C00,color:#000
    classDef external fill:#E8E8E8,stroke:#666666,color:#000
    classDef ci fill:#F0F0F0,stroke:#999999,color:#000
```
