# chickensoup269/zero_movie architecture

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

- Interactive diagram: https://gitdiagram.com/chickensoup269/zero_movie
- Repository: https://github.com/chickensoup269/zero_movie

## Overview

##### Main system components
a. Frontend (Next.js)
- Public user UI (movie listings, seat-picker, 3D-view)
- Admin UI (cinema/dashboard management)
b. Backend (Node.js + Express + TypeScript)
- API layer: routes & controllers
- Business logic: services
- Data access: Mongoose models
- Middlewares: auth, file-upload (multer), cron utilities
c. Database
- MongoDB cluster
d. File storage
- Local “uploads” folder (for images, receipts, etc.)
e. External services
- TMDB API (movie metadata)
- PayPal API (payment processing)
- EmailJS (notifications)
- Gemini AI API (chat/FAQs)
- Python recommendation script (exec’d via child_process)

##### Relationships & data flows
- User/browser ↔ Next.js frontend (HTTP/HTTPS)
- Frontend ↔ Backend REST/API calls
- Backend controllers → services → models → MongoDB
- Backend calls PayPal API for payments
- Backend calls TMDB API for up-to-date showtimes/genres
- Backend spawns Python process → recommendation engine → returns movie suggestions
- Backend sends emails via EmailJS
- Cron jobs (cronUtils) run background tasks (e.g., session cleanup, data seeding)
- File uploads handled via multer → stored in /uploads → served by backend

##### Architectural patterns & design principles
- Layered MVC-style separation: routes/controllers → services → data models
- Bounded contexts: Auth, Booking, Cinema, Movie, Payment, etc.
- “Hexagonal”/“Ports & Adapters” style: controllers adapt HTTP to internal services, services adapt to DB or external APIs
- Use of environment variables (.env) to decouple secrets & endpoints
- Frontend follows “app/(admin)” vs “app/(user)” segmentation for role-based routes

##### Technologies & frameworks to annotate
- Next.js (React + SSR/SSG) + TypeScript + Tailwind CSS + shadcn/ui + Three.js + Framer Motion
- Express.js + TypeScript + Mongoose
- MongoDB
- Python 3.x (recommendation script)
- External REST APIs: PayPal, TMDB, Gemini AI, EmailJS

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Zone
    subgraph "Client Zone"
        direction TB
        Browser["User Browser"]:::external
    end

    %% Presentation Zone
    subgraph "Presentation Zone"
        direction TB
        NextServer["Next.js Server (SSR)"]:::frontend
        PublicUI["Public UI"]:::frontend
        AdminUI["Admin UI"]:::frontend
        Layout["Global Layout & Styling"]:::frontend
        NextConfig["Next.js Config"]:::frontend
    end

    %% Frontend Services
    FrontendService["API Integration Services"]:::frontend

    %% Business Logic Zone
    subgraph "Business Logic Zone"
        direction TB
        APIGateway["Express API Gateway"]:::backend
        subgraph "Routes"
            direction TB
            AuthRoutes["Auth Routes"]:::backend
            BookingRoutes["Booking Routes"]:::backend
            CinemaRoutes["Cinema Routes"]:::backend
        end
        subgraph "Controllers"
            direction TB
            AuthCtrl["Auth Controller"]:::backend
            BookingCtrl["Booking Controller"]:::backend
            MovieCtrl["Movie Controller"]:::backend
            PaymentCtrl["Payment Controller"]:::backend
        end
        subgraph "Services"
            direction TB
            AuthSvc["Auth Services"]:::backend
            BookingSvc["Booking Services"]:::backend
            MovieSvc["Movie Services"]:::backend
            PaymentSvc["Payment Services"]:::backend
            FetchMovieSvc["TMDB Movie Fetcher"]:::backend
            FetchGenresSvc["TMDB Genres Fetcher"]:::backend
            SeedData["Seed Data"]:::backend
        end
        subgraph "Middlewares & Utils"
            direction TB
            AuthMiddleware["Auth Middleware"]:::backend
            MulterConfig["Multer Config"]:::backend
            CronUtils["Cron Utilities"]:::backend
            DBConfig["DB Config"]:::backend
            PayPalConfig["PayPal Config"]:::backend
        end
        subgraph "Models"
            direction TB
            UserModel["User Model"]:::backend
            BookingModel["Booking Model"]:::backend
            SessionModel["Session Model"]:::backend
            GuestSessionModel["Guest Session Model"]:::backend
        end
    end

    %% Data Zone
    subgraph "Data Zone"
        direction TB
        MongoDB["MongoDB Cluster"]:::database
        Uploads["File Storage (/uploads)"]:::storage
    end

    %% Integration Zone
    subgraph "Integration Zone"
        direction TB
        PayPalAPI["PayPal API"]:::external
        TMDBAPI["TMDB API"]:::external
        EmailJS["EmailJS"]:::external
        GeminiAI["Gemini AI API"]:::external
        PythonEngine["Python Recommendation Engine"]:::process
    end

    %% Connections
    Browser -->|"HTTP/HTTPS"| PublicUI
    Browser -->|"HTTP/HTTPS"| AdminUI
    PublicUI -->|"REST/JSON"| FrontendService
    AdminUI -->|"REST/JSON"| FrontendService
    FrontendService -->|"REST/JSON"| APIGateway
    APIGateway -->|"routes"| AuthRoutes
    APIGateway -->|"routes"| BookingRoutes
    APIGateway -->|"routes"| CinemaRoutes
    AuthRoutes -->|"calls"| AuthCtrl
    BookingRoutes -->|"calls"| BookingCtrl
    CinemaRoutes -->|"calls"| MovieCtrl
    AuthCtrl -->|"uses"| AuthSvc
    BookingCtrl -->|"uses"| BookingSvc
    MovieCtrl -->|"uses"| MovieSvc
    PaymentCtrl -->|"uses"| PaymentSvc
    AuthSvc -->|"CRUD"| UserModel
    BookingSvc -->|"CRUD"| BookingModel
    BookingSvc -->|"CRUD"| SessionModel
    BookingSvc -->|"CRUD"| GuestSessionModel
    MovieSvc -->|"exec python recommend.py"| PythonEngine
    MovieSvc -->|"fetch"| FetchMovieSvc
    MovieSvc -->|"fetch"| FetchGenresSvc
    PaymentSvc -->|"http"| PayPalAPI
    AuthCtrl -->|"http"| EmailJS
    AuthMiddleware -->|attached to| APIGateway
    MulterConfig -->|uploads| Uploads
    AuthCtrl -->|uses Multer| MulterConfig
    CronUtils -->|"scheduled tasks"| BookingSvc
    DBConfig -->|"connects to"| MongoDB
    PayPalConfig -->|"configures"| PaymentSvc
    Uploads -->|served by| APIGateway

    %% Integration arrows
    APIGateway -->|"child_process"| PythonEngine
    APIGateway -->|"http"| TMDBAPI
    APIGateway -->|"http"| GeminiAI

    %% Click Events
    click PublicUI "https://github.com/chickensoup269/zero_movie/tree/main/frontend/src/app/(user)"
    click AdminUI "https://github.com/chickensoup269/zero_movie/tree/main/frontend/src/app/(admin)"
    click FrontendService "https://github.com/chickensoup269/zero_movie/blob/main/frontend/src/services/*.ts"
    click Layout "https://github.com/chickensoup269/zero_movie/blob/main/frontend/src/app/layout.tsx"
    click Layout "https://github.com/chickensoup269/zero_movie/blob/main/frontend/src/app/globals.css"
    click NextConfig "https://github.com/chickensoup269/zero_movie/blob/main/frontend/next.config.ts"
    click APIGateway "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/server.ts"
    click AuthRoutes "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/routes/authRoutes.ts"
    click BookingRoutes "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/routes/bookingRoutes.ts"
    click CinemaRoutes "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/routes/cinemaRoutes.ts"
    click AuthCtrl "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/controllers/authController.ts"
    click BookingCtrl "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/controllers/bookingController.ts"
    click MovieCtrl "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/controllers/movieController.ts"
    click PaymentCtrl "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/controllers/paymentController.ts"
    click AuthSvc "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/services/authServices.ts"
    click BookingSvc "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/services/bookingServices.ts"
    click MovieSvc "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/services/movieServices.ts"
    click PaymentSvc "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/services/paymentServices.ts"
    click FetchMovieSvc "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/services/fetchmovieServices.ts"
    click FetchGenresSvc "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/services/fetchgenresServices.ts"
    click SeedData "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/services/seedData.ts"
    click UserModel "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/models/userModel.ts"
    click BookingModel "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/models/bookingModel.ts"
    click SessionModel "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/models/sessionModel.ts"
    click GuestSessionModel "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/models/guestsessionModel.ts"
    click AuthMiddleware "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/middlewares/auth.ts"
    click MulterConfig "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/config/multer.ts"
    click CronUtils "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/utils/cronUtils.ts"
    click DBConfig "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/config/db.ts"
    click PayPalConfig "https://github.com/chickensoup269/zero_movie/blob/main/backend/src/config/paypal.ts"
    click Uploads "https://github.com/chickensoup269/zero_movie/tree/main/backend/uploads"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#2B6CB0,stroke-width:1px;
    classDef backend fill:#DFFCCD,stroke:#2F855A,stroke-width:1px;
    classDef database fill:#FED7D7,stroke:#C53030,stroke-width:1px;
    classDef storage fill:#FEFCBF,stroke:#D69E2E,stroke-width:1px;
    classDef external fill:#EDF2F7,stroke:#718096,stroke-width:1px;
    classDef process fill:#F0FFF4,stroke:#38A169,stroke-width:1px;
```
