# kietvo1248/cinema-backend-system architecture

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

- Interactive diagram: https://gitdiagram.com/kietvo1248/cinema-backend-system
- Repository: https://github.com/kietvo1248/cinema-backend-system

## Overview

##### Project Type and Purpose
- This is a full-stack backend service (RESTful API) for a cinema system, written in Node.js/Express, persisting data in MongoDB, and secured via JWT. It exposes a set of HTTP endpoints for user auth, bookings, movie information, payments, promotions, and admin management.

##### File Structure Analysis
- Top-level:
- Dockerfile, .env.example → containerization & env config
- server.js (or src/app.js) → application entry point
- package.json / package-lock.json → dependencies & scripts
- swagger.js → API documentation setup
- src/config: external-service configurations (DB, Cloudinary, Cosmic CMS, multiple payment gateways)
- src/middleware: authorization layers by role (admin, employee, team, general auth)
- src/models: Mongoose schemas for all domain entities (User, Booking, Movie, Room, Invoice, etc.)
- src/routes: grouped by feature area (authentication, admin, booking, movie, payments, product, promotions, theater, userFeature)

##### Key Architectural Patterns
- Layered MVC-style division:
- Routes → Route definitions & validation
- Middleware → Auth, role checks
- Models → Data persistence layer (Mongoose)
- Controllers (inline in routes or in app.js) → Business logic
- Dependency injection of config objects
- External integrations via dedicated config modules
- JWT token-based stateless authentication

##### Main Components
a. Client (Web/Mobile)
b. API Gateway / Load Balancer (if using Docker + multiple replicas)
c. Node.js / Express App
– Route Layer (grouped feature modules)
– Middleware Layer (auth, role enforcement)
– Business Logic / Controllers
– Data Access Layer (Mongoose Models)
d. MongoDB Database (Atlas or local)
e. External Services (Cloudinary for media, Cosmic CMS for content, PayOS, VNPay gateway, Cash-on-delivery endpoint)
f. Swagger Docs (API documentation)
g. Docker Container & .env secrets store

##### Component Relationships & Data Flow
- Route dispatches to Middleware chain (JWT verification → role middleware) → Controller.
- Controller calls Mongoose Model methods → MongoDB (read/write).
- For upload, Controller calls Cloudinary.
- For CMS content, Controller calls Cosmic API.
- For payments, Controller calls PayOS/VNPay external endpoints → handles callbacks/webhooks.
- Logger/Counter model for metrics, Invoice generation, emailing (if any).
- Swagger.js serves at `/api-docs`.

##### Architectural Patterns & Design Principles
- Separation of Concerns: each folder handles a distinct responsibility
- Single Source of Truth: `.env` for secrets, `config/` modules for external integrations
- Role-Based Access Control: via distinct middleware per role (admin, employee, team)
- Modular Routing: feature-based route modules, easy to extend
- Stateless Auth: JWT tokens, no server session storage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer
    Client["Web/Mobile Client"]:::client
    APIGateway["API Gateway / Load Balancer"]:::infra

    %% Docker Container Boundary
    subgraph "Docker Container"
        direction TB
        Dockerfile["Dockerfile"]:::infra
        EnvFile[".env.example"]:::infra
        subgraph "Express Application"
            direction TB
            serverJS1["server.js"]:::entry
            serverJS2["src/app.js"]:::entry

            Swagger["Swagger Docs (/api-docs)"]:::docs

            subgraph "Config Modules"
                direction TB
                DBConfig["DB Config"]:::config
                CloudinaryConfig["Cloudinary Config"]:::config
                CosmicConfig["Cosmic CMS Config"]:::config
                PayOSConfig["PayOS Config"]:::config
                VNPayConfig["VNPay Config"]:::config
            end

            subgraph "Routes"
                direction TB
                AuthRoutes["Auth Routes"]:::route
                AdminRoutes["Admin Routes"]:::route
                BookingRoutes["Booking Routes"]:::route
                MovieRoutes["Movie Routes"]:::route
                PaymentsRoutes["Payments Routes"]:::route
                ProductRoutes["Product & Combo Routes"]:::route
                PromoRoutes["Promotions Routes"]:::route
                TheaterRoutes["Theater Routes"]:::route
                UserFeatureRoutes["User Feature Routes"]:::route
            end

            subgraph "Middleware"
                direction TB
                AuthMiddleware["Auth Middleware"]:::middleware
                AdminMiddleware["Admin Middleware"]:::middleware
                EmployeeMiddleware["Employee Middleware"]:::middleware
                TeamMiddleware["Team Middleware"]:::middleware
            end

            subgraph "Controllers / Services"
                direction TB
                Controllers["Controllers / Business Logic"]:::service
            end

            subgraph "Models"
                direction TB
                UserModel["User Model"]:::model
                BookingModel["Booking Model"]:::model
                MovieModel["Movie Model"]:::model
                RoomModel["Room Model"]:::model
                InvoiceModel["Invoice Model"]:::model
                CounterModel["Counter Model"]:::model
                PromotionModel["Promotion Model"]:::model
                ComboModel["Combo Model"]:::model
                ProductModel["Product Model"]:::model
                MovieNewsModel["MovieNews Model"]:::model
                CommentModel["Comment Model"]:::model
                ReplyModel["Reply Model"]:::model
            end
        end
    end

    %% Data Stores & External
    MongoDB["MongoDB"]:::database
    subgraph "External Services"
        direction TB
        Cloudinary["Cloudinary"]:::external
        Cosmic["Cosmic CMS"]:::external
        PayOS["PayOS Gateway"]:::external
        VNPay["VNPay Gateway"]:::external
        COD["Cash-on-Delivery Endpoint"]:::external
    end

    %% Connections
    Client --> APIGateway --> serverJS1
    serverJS1 --> serverJS2
    serverJS2 --> Swagger
    serverJS2 --> DBConfig
    serverJS2 --> CloudinaryConfig
    serverJS2 --> CosmicConfig
    serverJS2 --> PayOSConfig
    serverJS2 --> VNPayConfig

    serverJS2 --> AuthRoutes
    serverJS2 --> AdminRoutes
    serverJS2 --> BookingRoutes
    serverJS2 --> MovieRoutes
    serverJS2 --> PaymentsRoutes
    serverJS2 --> ProductRoutes
    serverJS2 --> PromoRoutes
    serverJS2 --> TheaterRoutes
    serverJS2 --> UserFeatureRoutes

    AuthRoutes --> AuthMiddleware --> Controllers
    AdminRoutes --> AdminMiddleware --> Controllers
    BookingRoutes --> AuthMiddleware --> Controllers
    MovieRoutes --> AuthMiddleware --> Controllers
    PaymentsRoutes --> AuthMiddleware --> Controllers
    ProductRoutes --> AuthMiddleware --> Controllers
    PromoRoutes --> AuthMiddleware --> Controllers
    TheaterRoutes --> AuthMiddleware --> Controllers
    UserFeatureRoutes --> AuthMiddleware --> Controllers

    Controllers --> UserModel
    Controllers --> BookingModel
    Controllers --> MovieModel
    Controllers --> RoomModel
    Controllers --> InvoiceModel
    Controllers --> CounterModel
    Controllers --> PromotionModel
    Controllers --> ComboModel
    Controllers --> ProductModel
    Controllers --> MovieNewsModel
    Controllers --> CommentModel
    Controllers --> ReplyModel

    UserModel --> MongoDB
    BookingModel --> MongoDB
    MovieModel --> MongoDB
    RoomModel --> MongoDB
    InvoiceModel --> MongoDB
    CounterModel --> MongoDB
    PromotionModel --> MongoDB
    ComboModel --> MongoDB
    ProductModel --> MongoDB
    MovieNewsModel --> MongoDB
    CommentModel --> MongoDB
    ReplyModel --> MongoDB

    Controllers --> Cloudinary
    Controllers --> Cosmic
    Controllers --> PayOS
    Controllers --> VNPay
    Controllers --> COD

    %% Click Events
    click Dockerfile "https://github.com/kietvo1248/cinema-backend-system/tree/main/Dockerfile"
    click EnvFile "https://github.com/kietvo1248/cinema-backend-system/blob/main/.env.example"
    click serverJS1 "https://github.com/kietvo1248/cinema-backend-system/blob/main/server.js"
    click serverJS2 "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/app.js"
    click Swagger "https://github.com/kietvo1248/cinema-backend-system/blob/main/swagger.js"
    click DBConfig "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/config/dbconfig.js"
    click CloudinaryConfig "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/config/cloudinary.js"
    click CosmicConfig "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/config/cosmic.js"
    click PayOSConfig "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/config/payOSConfig.js"
    click VNPayConfig "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/config/vnPayConfig.js"
    click AuthMiddleware "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/middleware/authMiddleware.js"
    click AdminMiddleware "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/middleware/adminMiddleware.js"
    click EmployeeMiddleware "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/middleware/employeeMiddleware.js"
    click TeamMiddleware "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/middleware/teamMiddleware.js"
    click UserModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/User.js"
    click BookingModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/Booking.js"
    click MovieModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/Movie.js"
    click RoomModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/Room.js"
    click InvoiceModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/Invoice.js"
    click CounterModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/Counter.js"
    click PromotionModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/Promotion.js"
    click ComboModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/Combo.js"
    click ProductModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/Product.js"
    click MovieNewsModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/MovieNews.js"
    click CommentModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/Comment.js"
    click ReplyModel "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/models/Reply.js"
    click AuthRoutes "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/routes/authentication/auth.js"
    click AdminRoutes "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/routes/admin/customerRoutes.js"
    click BookingRoutes "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/routes/booking/bookingRoute.js"
    click MovieRoutes "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/routes/movie/movieRoutes.js"
    click PaymentsRoutes "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/routes/payments/vnPaySandboxRotes.js"
    click ProductRoutes "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/routes/product/productRoutes.js"
    click PromoRoutes "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/routes/promotions/promotionsRoutes.js"
    click TheaterRoutes "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/routes/theather/room.js"
    click UserFeatureRoutes "https://github.com/kietvo1248/cinema-backend-system/blob/main/src/routes/userFeature/userFeatureRoutes.js"

    %% Styles
    classDef client fill:#DDEEFF,stroke:#1E90FF
    classDef infra fill:#E8E8E8,stroke:#888888,stroke-dasharray: 5, 5
    classDef entry fill:#CCE5FF,stroke:#004085
    classDef docs fill:#FFF3CD,stroke:#856404
    classDef config fill:#E2F0CB,stroke:#6FA878
    classDef route fill:#D1E7DD,stroke:#0F5132
    classDef middleware fill:#F8D7DA,stroke:#842029
    classDef service fill:#E3CEF6,stroke:#5F259F
    classDef model fill:#FFEBCC,stroke:#664D03
    classDef database fill:#D1ECF1,stroke:#0C5460,stroke-dasharray: 2, 2
    classDef external fill:#E2E3E5,stroke:#6C757D,stroke-dasharray: 2, 2
```
