# ryguigas0/espm-bubble-mvp-backend architecture

> Architecture diagram of the GitHub repository ryguigas0/espm-bubble-mvp-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryguigas0/espm-bubble-mvp-backend
- Repository: https://github.com/ryguigas0/espm-bubble-mvp-backend

## Overview

##### Project Type & Purpose
- This is a Node.js/TypeScript backend monolith built with NestJS that exposes RESTful APIs for user management, events, and event attendance.
- It uses JWT for authentication, MongoDB (via Mongoose) for data storage, and is containerized via Docker/Docker Compose.

##### File Structure
- Top-level concerns:
- Dockerfile, docker-compose.yaml & dev-compose.yaml (container definitions)
- .env.example (environment variables)
- src/ (application code)
- test/ (end‐to‐end tests)
- src/ subdirectories map one‐to‐one to NestJS modules:
- src/auth – authentication + guards + login DTOs
- src/users – user CRUD, DTOs, Mongoose schemas
- src/events – event CRUD, DTOs, Mongoose schemas
- src/user-events – user attendance endpoints + DTOs
- src/config – centralized config for JWT & Mongo
- src/app – root AppModule + global controller/service
- src/util – request helpers, shared schemas
- Each module follows Nest’s Layered Pattern: Controller → Service → Mongoose Model (schema).

##### Extract Key Insights from README
- Modern framework (NestJS), JWT auth, MongoDB + Mongoose, Docker support, linting/formatting with ESLint/Prettier.
- Dev vs. full-stack compose files: dev-compose.yaml (Mongo + Mongo-Express) vs. docker-compose.yaml (entire stack).

a. Main Components
- Client(s) (e.g., Insomnia, any front-end)
- API Gateway – NestJS HTTP server (single Docker container)
– Subcomponents (modules):
· AuthModule (login, JWT guard)
· UsersModule (user profiles, friends, block)
· EventsModule (create/update events)
· UserEventsModule (attend/unattend events)
· ConfigModule (env management)
- Database Tier
– MongoDB (primary data store)
– Mongo-Express (admin UI)
- DevOps / Infrastructure
– Docker daemon & Docker Compose orchestrating three containers:
· bubble-backend (built from Dockerfile)
· mongo-db
· mongo-express
b. Relationships & Data Flows
1. Client → HTTP(S) → NestJS Controllers
2. Controllers → Services (business logic)
3. Services → Mongoose Models → MongoDB
4. AuthGuard intercepts protected routes, validates JWT via AuthService
5. ConfigService injects environment variables into modules
6. Docker Compose networking: backend ↔ mongo via internal bridge; mongo-express ↔ mongo
c. Architectural Patterns & Principles
- Modular Monolith (Nest modules)
- Layered Architecture (Controller → Service → Data Access)
- Dependency Injection (built into NestJS)
- 12-Factor App principles (config via ENV, containerization)
d. Key Technologies
- NestJS & TypeScript
- Mongoose + MongoDB
- JSON Web Tokens for auth
- Docker & Docker Compose
- ESLint & Prettier for code quality

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global Entities
    Client["Client (Insomnia / Frontend)"]:::client
    Client -->|"HTTP(S) REST"| APIServer

    %% Docker Compose Network
    subgraph "Docker Compose Network"
        direction TB
        APIServer["Bubble Backend (NestJS)"]:::app
        MongoDB[(MongoDB)]:::db
        MongoExpress["Mongo-Express"]:::db
        APIServer -->|"TCP 27017"| MongoDB
        MongoExpress -->|"TCP 27017"| MongoDB
    end

    %% API Server Internals
    subgraph "API Server Modules"
        direction TB
        ConfigModule["ConfigModule"]:::module
        AuthModule["AuthModule"]:::module
        UsersModule["UsersModule"]:::module
        EventsModule["EventsModule"]:::module
        UserEventsModule["UserEventsModule"]:::module
        Bootstrap["Bootstrap (main.ts)"]:::module

        Bootstrap -->|imports| ConfigModule
        Bootstrap -->|imports| AuthModule
        Bootstrap -->|imports| UsersModule
        Bootstrap -->|imports| EventsModule
        Bootstrap -->|imports| UserEventsModule

        %% ConfigModule
        subgraph "ConfigModule"
            direction TB
            JWTConfig["jwt-config.ts"]:::file
            MdbConfig["mdb-config.ts"]:::file
        end

        %% AuthModule
        subgraph "AuthModule"
            direction TB
            AuthController["AuthController"]:::component
            AuthService["AuthService"]:::component
            AuthGuard["AuthGuard"]:::component
            LoginDTO["login.dto.ts"]:::file
            TokenPayloadDTO["token-payload.dto.ts"]:::file
            AuthController -->|calls| AuthService
            AuthService -->|uses| LoginDTO
            AuthService -->|generates| TokenPayloadDTO
            AuthGuard -->|validates JWT| AuthService
        end

        %% UsersModule
        subgraph "UsersModule"
            direction TB
            UsersController["UsersController"]:::component
            UsersMeController["UsersMeController"]:::component
            UsersService["UsersService"]:::component
            CreateUserDTO["create-user.dto.ts"]:::file
            UpdateUserDTO["update-user.dto.ts"]:::file
            AddFriendDTO["add-friend.dto.ts"]:::file
            BlockUserDTO["block-user.dto.ts"]:::file
            UserDTO["user.dto.ts"]:::file
            UserSchema["user.schema.ts"]:::file
            UserAttendanceSchema["user-attendance.schema.ts"]:::file
            UsersController -->|calls| UsersService
            UsersMeController -->|calls| UsersService
            UsersService -->|reads/writes| UserSchema
            UsersService -->|reads/writes| UserAttendanceSchema
        end

        %% EventsModule
        subgraph "EventsModule"
            direction TB
            EventsController["EventsController"]:::component
            EventsService["EventsService"]:::component
            CreateEventDTO["create-event.dto.ts"]:::file
            UpdateEventDTO["update-event.dto.ts"]:::file
            EventSchema["event.schema.ts"]:::file
            EventAttendanceSchema["event-attendance.schema.ts"]:::file
            EventsController -->|calls| EventsService
            EventsService -->|reads/writes| EventSchema
            EventsService -->|reads/writes| EventAttendanceSchema
        end

        %% UserEventsModule
        subgraph "UserEventsModule"
            direction TB
            UserEventsController["UserEventsController"]:::component
            UserEventsService["UserEventsService"]:::component
            CoordsDTO["coords.dto.ts"]:::file
            PushAttendanceDTO["push-attendance.dto.ts"]:::file
            UserEventsController -->|calls| UserEventsService
            UserEventsService -->|uses| CoordsDTO
            UserEventsService -->|uses| PushAttendanceDTO
        end
    end

    %% Utilities & Tests
    subgraph "Utilities & Tests"
        direction TB
        LogReq["loged-in-req.ts"]:::file
        CoordsSchema["coordinates.schema.ts"]:::file
        E2ETests["test/ (e2e tests)"]:::file
    end

    %% Relationships to Utilities & DB
    AuthService -->|loads config| ConfigModule
    UsersService -->|loads config| ConfigModule
    EventsService -->|loads config| ConfigModule
    UserEventsService -->|loads config| ConfigModule
    AuthService -->|data| MongoDB
    UsersService -->|data| MongoDB
    EventsService -->|data| MongoDB
    UserEventsService -->|data| MongoDB

    %% Click Events
    click AuthModule "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/auth/auth.module.ts"
    click AuthController "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/auth/auth.controller.ts"
    click AuthService "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/auth/auth.service.ts"
    click AuthGuard "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/auth/auth.guard.ts"
    click LoginDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/auth/dto/login.dto.ts"
    click TokenPayloadDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/auth/dto/token-payload.dto.ts"

    click UsersModule "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/users.module.ts"
    click UsersController "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/users.controller.ts"
    click UsersMeController "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/users-me.controller.ts"
    click UsersService "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/users.service.ts"
    click CreateUserDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/dto/create-user.dto.ts"
    click UpdateUserDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/dto/update-user.dto.ts"
    click AddFriendDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/dto/add-friend.dto.ts"
    click BlockUserDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/dto/block-user.dto.ts"
    click UserDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/dto/user.dto.ts"
    click UserSchema "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/schema/user.schema.ts"
    click UserAttendanceSchema "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/users/schema/user-attendance.schema.ts"

    click EventsModule "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/events/events.module.ts"
    click EventsController "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/events/events.controller.ts"
    click EventsService "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/events/events.service.ts"
    click CreateEventDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/events/dto/create-event.dto.ts"
    click UpdateEventDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/events/dto/update-event.dto.ts"
    click EventSchema "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/events/schemas/event.schema.ts"
    click EventAttendanceSchema "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/events/schemas/event-attendance.schema.ts"

    click UserEventsModule "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/user-events/user-events.module.ts"
    click UserEventsController "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/user-events/user-events.controller.ts"
    click UserEventsService "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/user-events/user-events.service.ts"
    click CoordsDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/user-events/dto/coords.dto.ts"
    click PushAttendanceDTO "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/user-events/dto/push-attendance.dto.ts"

    click ConfigModule "https://github.com/ryguigas0/espm-bubble-mvp-backend/tree/main/src/config"
    click JWTConfig "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/config/jwt-config.ts"
    click MdbConfig "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/config/mdb-config.ts"

    click Bootstrap "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/main.ts"
    click LogReq "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/util/loged-in-req.ts"
    click CoordsSchema "https://github.com/ryguigas0/espm-bubble-mvp-backend/blob/main/src/util/schemas/coordinates.schema.ts"
    click E2ETests "https://github.com/ryguigas0/espm-bubble-mvp-backend/tree/main/test/"

    %% Styles
    classDef client fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef app fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef db fill:#ffdd99,stroke:#333,stroke-width:1px
    classDef module fill:#f2f2f2,stroke:#666,stroke-width:1px
    classDef component fill:#e6e6e6,stroke:#666,stroke-width:1px
    classDef file fill:#ffffff,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2
```
