# namnguyen1909/hotel-platform architecture

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

- Interactive diagram: https://gitdiagram.com/namnguyen1909/hotel-platform
- Repository: https://github.com/namnguyen1909/hotel-platform

## Overview

##### Project Type and Purpose
- This is a monorepo full-stack Hotel Platform Management System.
- Frontend: React SPA (Vite + Material-UI).
- Backend: Django 5.2.4 REST API (Django REST Framework).
- Purpose: manage rooms, bookings, customers, staff, payments, analytics, and automated tasks.

##### File Structure
- Top-level directories:
- hotelplatformapi/ → Django project & app (“hotelplatform”).
- hotelplatformweb-vite/ → React frontend.
- render.yaml, DEPLOYMENT.md → deployment configuration.
- Backend modules: models, serializers, views, permissions, signals, admin, management/commands (cron seed).
- Frontend modules: pages/, components/, services/apis.js, hooks/useSmartPolling.js, theme/.
- Config files: .env.example, requirements.txt, package.json (root & frontend), render.yaml.

##### README Insights
- Monorepo with “npm run dev” to start both servers.
- Core technologies: PostgreSQL, JWT Auth, Cloudinary, VNPay, Smart Polling, Gunicorn, Render.com, Cron-job.org.
- Architectural note: separation of concerns (API vs. UI), automated tasks via external cron, external services.

##### Main Components
a. Client Layer
- Browser (Desktop/Mobile)
- React SPA (UI components, Router, Axios, Smart-Polling Hook)
b. API Layer
- Django REST Framework
- Authentication (JWT flow)
- Business logic (views.py)
- Serializers & permissions
c. Data Layer
- PostgreSQL database
- Django ORM (models.py)
d. Admin Interface
- Django Admin (static + templates)
e. External Services
- VNPay Payment Gateway
- Cloudinary (media storage)
- cron-job.org (scheduled POST to /api/tasks/update-room-status/)
f. Hosting/Infra
- Render.com (two services: frontend & backend)
- Gunicorn + WhiteNoise (static files)
- Environment Variables (for secrets, CORS, DB URL)

##### Relationships & Data Flow
- Browser → HTTP(S) to React static assets on Render CDN
- React → REST calls (Axios) → Django API (api/* endpoints)
- Django → ORM → PostgreSQL
- Django → Cloudinary SDK → Cloudinary (upload/download)
- Django → outgoing URL to VNPay and VNPay callback (redirect endpoint)
- cron-job.org → scheduled POST → Django task endpoint → updates room statuses
- Django Admin UI uses internal URLs and static assets served by WhiteNoise

##### Architectural Patterns & Principles
- Monorepo: unified repo for coordinated releases (package.json scripts)
- MVC on backend: models ↔ views ↔ templates/serializers
- Single-Page Application frontend with service layer and custom hooks
- Explicit separation of UI vs. API vs. Data
- Stateless JWT authentication with role-based permissions
- Smart polling with Page Visibility API for real-time updates
- External cron for scheduled background jobs

##### Detail Without Overthinking
- Major module (e.g., views.py, serializers.py, management/commands).
- Admin interface separately from the REST API.
- Build & deployment pipeline: concurrently/dev script, npm run build, gunicorn start, Render.com.
- Environment variable usage is noted for secrets injection.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser (Desktop/Mobile)"]
        ReactSPA["React SPA"]
    end
    Browser -->|"loads assets (HTTP(S))"| ReactSPA

    %% Frontend Layer
    subgraph "Frontend Layer (React App)" 
        direction TB
        App["App.jsx (Router Entry)"]:::frontend
        UIComponents["UI Components (Material-UI)"]:::frontend
        APIService["apis.js (Axios Service)"]:::frontend
        AuthService["auth.js (JWT Service)"]:::frontend
        PollingHook["useSmartPolling.js"]:::frontend
        Theme["theme.js"]:::frontend
    end
    ReactSPA -->|"renders UI & calls services"| App
    App --> UIComponents
    App --> APIService
    App --> AuthService
    App --> PollingHook
    App --> Theme

    %% API Layer
    subgraph "API Layer (Django REST Framework)"
        direction TB
        URLRouting["urls.py (URL Routing)"]:::backend
        Views["views.py (Business Logic)"]:::backend
        Serializers["serializers.py"]:::backend
        Permissions["permissions.py"]:::backend
        Paginators["paginators.py"]:::backend
        AdminConfig["admin.py (Admin Config)"]:::backend
        Migrations["migrations/"]:::backend
        Management["seed.py & task cmd"]:::backend
    end
    ReactSPA -->|"REST calls (JWT auth)"| URLRouting
    URLRouting --> Views
    Views --> Serializers
    Views --> Permissions
    Views --> Paginators
    Views --> Models["models.py"]:::backend
    Views --> AdminConfig
    Views --> Management

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB[(PostgreSQL)]:::db
    end
    Models -->|"ORM queries (SQL)"| DB
    Migrations --> DB

    %% External Services
    subgraph "External Services"
        direction TB
        Cloudinary["Cloudinary (Media Storage)"]:::external
        VNPay["VNPay Payment Gateway"]:::external
        Cron["cron-job.org"]:::external
    end
    Views -->|"upload/download"| Cloudinary
    Views -->|"redirect & callback"| VNPay
    Cron -->|"POST /api/tasks/update-room-status/"| URLRouting

    %% Admin Interface
    AdminUI["Django Admin UI"]:::backend
    AdminConfig --> AdminUI
    AdminUI -->|"serves via WhiteNoise"| StaticFiles["WhiteNoise Static Files"]:::infra

    %% Infrastructure / Hosting
    subgraph "Hosting & Infra"
        direction TB
        RenderFrontend["Render.com (Frontend Service)"]:::infra
        RenderBackend["Render.com (Backend Service)"]:::infra
        Gunicorn["Gunicorn"]:::infra
        EnvVars["Environment Variables"]:::infra
        RenderConfig["render.yaml"]:::infra
        DeployDocs["DEPLOYMENT.md"]:::infra
        EnvExample[".env.example"]:::infra
        BackendDeps["requirements.txt"]:::infra
        FrontendDeps["hotelplatformweb-vite/package.json"]:::infra
        MonorepoScripts["package.json"]:::infra
    end
    ReactSPA --> RenderFrontend
    URLRouting --> RenderBackend
    RenderBackend --> Gunicorn
    RenderBackend --> StaticFiles
    RenderFrontend --> EnvVars
    RenderBackend --> EnvVars

    %% Click Events
    click App "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformweb-vite/src/App.jsx"
    click UIComponents "https://github.com/namnguyen1909/hotel-platform/tree/main/hotelplatformweb-vite/src"
    click APIService "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformweb-vite/src/services/apis.js"
    click AuthService "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformweb-vite/src/services/auth.js"
    click PollingHook "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformweb-vite/src/hooks/useSmartPolling.js"
    click Theme "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformweb-vite/src/theme/theme.js"
    click Views "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformapi/hotelplatform/views.py"
    click URLRouting "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformapi/hotelplatform/urls.py"
    click Serializers "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformapi/hotelplatform/serializers.py"
    click Permissions "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformapi/hotelplatform/permissions.py"
    click Paginators "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformapi/hotelplatform/paginators.py"
    click Models "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformapi/hotelplatform/models.py"
    click Migrations "https://github.com/namnguyen1909/hotel-platform/tree/main/hotelplatformapi/hotelplatform/migrations"
    click AdminConfig "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformapi/hotelplatform/admin.py"
    click Management "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformapi/hotelplatform/management/commands/seed.py"
    click Cron "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformapi/test_room_status_task.py"
    click RenderConfig "https://github.com/namnguyen1909/hotel-platform/blob/main/render.yaml"
    click DeployDocs "https://github.com/namnguyen1909/hotel-platform/blob/main/DEPLOYMENT.md"
    click EnvExample "https://github.com/namnguyen1909/hotel-platform/blob/main/.env.example"
    click BackendDeps "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformapi/requirements.txt"
    click FrontendDeps "https://github.com/namnguyen1909/hotel-platform/blob/main/hotelplatformweb-vite/package.json"
    click MonorepoScripts "https://github.com/namnguyen1909/hotel-platform/blob/main/package.json"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef backend fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef db fill:#CFD8DC,stroke:#455A64,color:#455A64;
    classDef external fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef infra fill:#E1BEE7,stroke:#4A148C,color:#4A148C;
```
