# ntdquan/g-score architecture

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

- Interactive diagram: https://gitdiagram.com/ntdquan/g-score
- Repository: https://github.com/ntdquan/g-score

## Overview

##### Project Overview
- G-Score is a full-stack web application. The backend is a Django-based server (evidenced by files such as manage.py, settings.py, and the Django app structure inside “backend/g_score”), while the frontend is a React application built with Vite (as seen in the “frontend” directory, including App.jsx, main.jsx, and vite.config.js).
- The project is containerized, with Dockerfiles in both frontend and backend, and uses docker-compose for orchestration. The README also explains that data seeding is performed (via a management command) and that the initial startup might take a while due to free-tier limitations on Render.

##### Analyzing the File Structure
- Top-Level Directories: “frontend” and “backend” indicate clear separation. Frontend contains source code for the React application alongside configuration for Tailwind CSS and ESLint. Backend contains a full Django project along with a specific Django app called “g_score” that holds models, views, serializers, migrations, and management commands (including a seed script).
- Build/Deployment: The presence of Dockerfiles in both the frontend and backend directories, and a docker-compose.yml file at the project root, confirms a containerized, service-oriented deployment.
- Additional Files: Files like “data/diem_thi_thpt_2024.csv” within the backend suggest that the system imports external data into the database via seeding routines.

##### Key Components
a. Client / Browser:
- Represents the end-user interface which interacts with the frontend (React application).

b. Frontend Service:
- A containerized service running the React application (using Vite) along with supporting assets (CSS, images, fonts, etc.).
- Represents pages (Home, Reports, Search, Settings) and UI components (Layout, SideBar, StatisticChart, Table).
- Communicates with the backend via API calls (the APIService, as seen in “frontend/src/Service/APIService.jsx”).

c. Backend Service:
- A Django server with multiple roles:
- Django core (managing routing with asgi.py, wsgi.py, settings, urls).
- “g_score” Django app managing score-related logic, models, views, serializers, and admin functions.
- Data seeding and migrations (files under commands and migrations) for seeding and managing the database schema.
- The backend service interacts with its data sources, and exposes RESTful endpoints used by the frontend.

d. Datastore / Data Source:
- While not explicitly represented by a separate directory or service in the file tree, the backend likely relies on a database (even if it is a default SQLite during development or a more robust database in production). Indicate this as an external component.
- Additionally, the CSV file in “backend/data/” suggests a data feeding mechanism used during seeding.

e. Docker & Orchestration Layer:
- A docker-compose layer that orchestrates both the frontend and backend containers (and possibly other services if they are added later, such as a database container).

##### Relationships and Interactions
- The Client accesses the Frontend through a web browser.
- The Frontend makes API requests to the Backend service.
- The Backend processes these requests through Django’s HTTP routing and the “g_score” app endpoints.
- During startup or on command, the backend initiates data seeding (making use of the CSV file) and migrates the database as needed.
- All services run inside Docker containers, coordinated by docker-compose.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear division between client-side (React) and server-side (Django) responsibilities.
- Containerization: Each service (frontend and backend) is containerized to ensure consistent deployment and scalability.
- RESTful API Design: Backend endpoints (e.g., defined in “backend/g_score/urls.py” and routed in the main urls.py) serve as an interface for frontend communication.
- Modular Design: The Django app “g_score” is modular with its own models, migrations, views, and serializers; the React application is composed of multiple reusable components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client("Client / Browser"):::client
    end

    %% Frontend Service Layer
    subgraph "Frontend Service (React Application)"
        FE("React App"):::frontend
        API("API Service"):::service
    end

    %% Backend Service Layer
    subgraph "Backend Service (Django Server)"
        Django("Django Server"):::backend
        GScore("G-Score App"):::backend
        Seeding("Data Seeding"):::seeding
    end

    %% DataStore
    subgraph "DataStore"
        DB("Database (SQLite/PostgreSQL)"):::database
    end

    %% Docker & Orchestration Layer
    subgraph "Docker & Orchestration"
        Orchestrator("docker-compose"):::orchestration
    end

    %% Data Flow Connections
    Client -->|"HTTP_request"| FE
    FE -->|"API_calls"| Django
    Django -->|"CRUD_operations"| DB
    Seeding -->|"Seed_from_CSV"| DB
    Django ---|"Incorporates"| GScore

    %% Orchestration links
    Orchestrator --- FE
    Orchestrator --- Django

    %% Click Events for Frontend Service
    click FE "https://github.com/ntdquan/g-score/tree/main/frontend/"
    click FE "https://github.com/ntdquan/g-score/blob/main/frontend/src/App.jsx"
    click FE "https://github.com/ntdquan/g-score/blob/main/frontend/src/main.jsx"
    click FE "https://github.com/ntdquan/g-score/blob/main/frontend/vite.config.js"
    click FE "https://github.com/ntdquan/g-score/tree/main/frontend/Dockerfile"
    click API "https://github.com/ntdquan/g-score/blob/main/frontend/src/Service/APIService.jsx"

    %% Click Events for Backend Service
    click Django "https://github.com/ntdquan/g-score/tree/main/backend/"
    click Django "https://github.com/ntdquan/g-score/blob/main/backend/manage.py"
    click Django "https://github.com/ntdquan/g-score/blob/main/backend/backend/settings.py"
    click Django "https://github.com/ntdquan/g-score/blob/main/backend/backend/urls.py"
    click GScore "https://github.com/ntdquan/g-score/tree/main/backend/g_score/"
    click Seeding "https://github.com/ntdquan/g-score/blob/main/backend/g_score/management/commands/seed.py"
    click Seeding "https://github.com/ntdquan/g-score/blob/main/backend/data/diem_thi_thpt_2024.csv"

    %% Click Events for Docker & Orchestration
    click Orchestrator "https://github.com/ntdquan/g-score/blob/main/docker-compose.yml"
    click Orchestrator "https://github.com/ntdquan/g-score/tree/main/backend/Dockerfile"
    click Orchestrator "https://github.com/ntdquan/g-score/tree/main/frontend/Dockerfile"

    %% Styles
    classDef client fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef frontend fill:#AED6F1,stroke:#2874A6,stroke-width:2px;
    classDef service fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
    classDef backend fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef seeding fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef database fill:#A9DFBF,stroke:#239B56,stroke-width:2px;
    classDef orchestration fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
```
