# luongtantai200803/shopacc architecture

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

- Interactive diagram: https://gitdiagram.com/luongtantai200803/shopacc
- Repository: https://github.com/luongtantai200803/shopacc

## Overview

##### Project type and purpose
- ShopAcc is a backend-only, monolithic REST API service built in Python/Flask.
- Its purpose is to expose CRUD endpoints for game accounts, handle user auth (JWT), manage orders (virtual payments), and emit real-time events via WebSockets/Sockets.

##### File structure
- Top-level configuration and Docker artifacts:
- Dockerfile, docker-compose.yml, nginx.conf, gunicorn.conf.py, .github/workflows/deploy.yml
- main.py (entry point), requirements.txt, pytest.ini, test_*.py, tests/
- app/ folder defines the Flask application:
- app/config.py – environment & Flask settings
- app/extensions.py – initializes extensions (SQLAlchemy, JWT, SocketIO, etc.)
- app/error_handler.py, app/exceptions.py – centralized error handling
- app/models/ – SQLAlchemy models (User, Account)
- app/routes/ – Blueprints for auth, account, order endpoints
- app/sockets.py – real-time notifications via WebSockets
- app/intents.json – domain data for game-account categories or intents
- instance/ holds the local SQLite DB file (instance/mydb.sqlite3)
- migrations/ is the Alembic setup for versioned schema changes

##### README
- Confirms core features (auth, CRUD, buy/sell, roles)
- Technology stack: Flask, REST, SQLAlchemy + MySQL/PostgreSQL, JWT, Gunicorn, Nginx, Docker, CD on Railway/AWS
- Local run instructions & environment setup

##### Main components
a. External Clients
- Web or Mobile UIs (or Postman/other API consumers)
b. Reverse-Proxy Layer
- Nginx (TLS termination, load balancing, static asset serving if any)
c. WSGI Server
- Gunicorn (multiple worker processes)
d. Flask Application
- Config & Extensions
- Routing layer (Blueprints: Auth, Account, Order)
- Business logic & error handlers
- Sockets namespace for real-time updates (via Flask-SocketIO)
e. Data Layer
- SQLAlchemy ORM
- Relational Database (MySQL/PostgreSQL in production; SQLite for local dev)
- Alembic migrations
f. DevOps & CI/CD
- Docker containers (App, DB) orchestrated via docker-compose
- GitHub Actions → deploy.yml for automated tests & deploy
- Deployment target (Railway / AWS)

##### Relationships and data flows
- Clients ↔ HTTPS ↔ Nginx
- Nginx → Gunicorn workers → Flask app
- Flask → SQLAlchemy → RDBMS
- Flask-SocketIO communicates bi-directionally with clients over WebSockets
- CI pipeline triggers container builds, tests, and pushes to staging/production
- Alembic handles database schema migrations before startup

##### Architectural patterns and design principles
- Layered architecture: Presentation (routes + sockets), Service (business logic), Data (models + migrations)
- Separation of concerns: Blueprints for modular routing, extensions for decoupled middleware
- Token-based security (JWT) governing admin vs user roles
- Infrastructure as code: Dockerfile, docker-compose, Nginx config, CI workflows

- End-to-end flow, from client requests down to DB IO and back
- Distinguish sync HTTP paths from async WebSocket channels
- Where environment config lives (app/config.py + .env) and migrations kick in
- Call out the CI/CD pipeline and container orchestration as part of the “deployment” layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients["Web/Mobile UI or API Client"]:::external

    %% App Container
    subgraph "App Container"
        style AppContainer stroke:#000,stroke-width:1px
        Nginx["Nginx (Reverse Proxy)"]:::infra
        Gunicorn["Gunicorn (WSGI Server)"]:::infra
        subgraph "Flask Application" 
            Config["app/config.py"]:::app
            Extensions["app/extensions.py"]:::app
            ErrorHandler["app/error_handler.py\napp/exceptions.py"]:::app
            LogRequest["app/log_request.py"]:::app
            subgraph "Routes (Blueprints)"
                AuthRoute["auth.py"]:::app
                AccountRoute["account.py"]:::app
                OrderRoute["order.py"]:::app
            end
            Sockets["app/sockets.py"]:::app
            Intents["app/intents.json"]:::app
            subgraph "Models"
                UserModel["app/models/user.py"]:::data
                AccModel["app/models/acc.py"]:::data
            end
            Main["main.py"]:::app
        end
    end

    %% DB Container
    subgraph "DB Container"
        DB["Relational DB\n(MySQL/PostgreSQL/SQLite)"]:::data
        SQLite["instance/mydb.sqlite3"]:::data
        subgraph "Migrations"
            AlembicIni["migrations/alembic.ini"]:::data
            EnvPy["migrations/env.py"]:::data
            Version1["migrations/versions/137dfc8f19bb_initial_migration.py"]:::data
            Version2["migrations/versions/3568de11d166_add_email_and_google_id_to_user.py"]:::data
        end
    end

    %% CI/CD & DevOps
    subgraph "CI/CD & Deployment"
        GitHubActions[".github/workflows/deploy.yml"]:::devops
        DockerfileDef["Dockerfile"]:::devops
        Compose["docker-compose.yml"]:::devops
        README["README.md"]:::devops
    end

    %% Test & Config
    subgraph "Testing & Config"
        Requirements["requirements.txt"]:::devops
        Gitignore[".gitignore"]:::devops
        PytestIni["pytest.ini"]:::devops
        TestClient["test_client.py"]:::devops
        TestServer["test_server.py"]:::devops
        TestsDir["tests/"]:::devops
    end

    %% Flows
    Clients -->|"HTTPS/HTTP"| Nginx
    Nginx -->|"WSGI"| Gunicorn
    Gunicorn -->|"Flask App Request"| Main
    Main --> Config
    Main --> Extensions
    Extensions --> ErrorHandler
    Main --> LogRequest
    Main --> AuthRoute
    Main --> AccountRoute
    Main --> OrderRoute
    Main --> Sockets
    Main --> Intents
    Extensions --> UserModel
    Extensions --> AccModel
    Main --> UserModel
    Main --> AccModel
    UserModel -->|"SQL"| DB
    AccModel -->|"SQL"| DB
    AlembicIni --> EnvPy
    EnvPy --> Version1
    EnvPy --> Version2

    %% WebSocket Async
    Sockets -.->|"WebSocket"| Clients

    %% DevOps Triggers
    GitHubActions -.->|"Trigger Build/Test/Deploy"| DockerfileDef
    DockerfileDef -->|"Build Image"| Compose
    Compose -->|"Deploy Containers"| AppContainer
    Compose -->|"Deploy DB"| DB
    GitHubActions -.->|"Docs & Config"| README

    %% Click Events
    click Nginx "https://github.com/luongtantai200803/shopacc/blob/main/nginx.conf"
    click Gunicorn "https://github.com/luongtantai200803/shopacc/blob/main/gunicorn.conf.py"
    click Main "https://github.com/luongtantai200803/shopacc/blob/main/main.py"
    click Config "https://github.com/luongtantai200803/shopacc/blob/main/app/config.py"
    click Extensions "https://github.com/luongtantai200803/shopacc/blob/main/app/extensions.py"
    click ErrorHandler "https://github.com/luongtantai200803/shopacc/blob/main/app/error_handler.py"
    click ErrorHandler "https://github.com/luongtantai200803/shopacc/blob/main/app/exceptions.py"
    click AuthRoute "https://github.com/luongtantai200803/shopacc/blob/main/app/routes/auth.py"
    click AccountRoute "https://github.com/luongtantai200803/shopacc/blob/main/app/routes/account.py"
    click OrderRoute "https://github.com/luongtantai200803/shopacc/blob/main/app/routes/order.py"
    click Sockets "https://github.com/luongtantai200803/shopacc/blob/main/app/sockets.py"
    click Intents "https://github.com/luongtantai200803/shopacc/blob/main/app/intents.json"
    click LogRequest "https://github.com/luongtantai200803/shopacc/blob/main/app/log_request.py"
    click UserModel "https://github.com/luongtantai200803/shopacc/blob/main/app/models/user.py"
    click AccModel "https://github.com/luongtantai200803/shopacc/blob/main/app/models/acc.py"
    click SQLite "https://github.com/luongtantai200803/shopacc/blob/main/instance/mydb.sqlite3"
    click AlembicIni "https://github.com/luongtantai200803/shopacc/blob/main/migrations/alembic.ini"
    click EnvPy "https://github.com/luongtantai200803/shopacc/blob/main/migrations/env.py"
    click Version1 "https://github.com/luongtantai200803/shopacc/blob/main/migrations/versions/137dfc8f19bb_initial_migration.py"
    click Version2 "https://github.com/luongtantai200803/shopacc/blob/main/migrations/versions/3568de11d166_add_email_and_google_id_to_user.py"
    click DockerfileDef "https://github.com/luongtantai200803/shopacc/tree/main/Dockerfile"
    click Compose "https://github.com/luongtantai200803/shopacc/blob/main/docker-compose.yml"
    click GitHubActions "https://github.com/luongtantai200803/shopacc/blob/main/.github/workflows/deploy.yml"
    click Requirements "https://github.com/luongtantai200803/shopacc/blob/main/requirements.txt"
    click Gitignore "https://github.com/luongtantai200803/shopacc/blob/main/.gitignore"
    click PytestIni "https://github.com/luongtantai200803/shopacc/blob/main/pytest.ini"
    click TestClient "https://github.com/luongtantai200803/shopacc/blob/main/test_client.py"
    click TestServer "https://github.com/luongtantai200803/shopacc/blob/main/test_server.py"
    click TestsDir "https://github.com/luongtantai200803/shopacc/tree/main/tests/"

    %% Styles
    classDef external fill:#e0f7e0,stroke:#333,stroke-width:1px
    classDef infra fill:#cce0ff,stroke:#333,stroke-width:1px
    classDef app fill:#fff4cc,stroke:#333,stroke-width:1px
    classDef data fill:#ffe0b3,stroke:#333,stroke-width:1px
    classDef devops fill:#f2ccff,stroke:#333,stroke-width:1px
```
