# tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow architecture

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

- Interactive diagram: https://gitdiagram.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow
- Repository: https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow

## Overview

##### Project type and purpose
- CodeFlow is a full-stack, monolithic web application for educational project management, with a Next.js 14 frontend and an Express + TypeScript backend.
- It integrates deeply with GitHub (OAuth, REST API, Webhooks, Actions) and Google Gemini AI for automated code reviews and code-quality analysis.

##### File structure
- Top level:
- src/client – Next.js frontend (React + TypeScript, Tailwind CSS, React Query, i18n, rich-text editor, charts)
- src/server – Express.js backend (REST controllers, services, models, Sequelize ORM, middleware, Swagger, Webhook handlers)
- src/database – SQL scripts and schema snapshots
- docs – report, design docs, images
- Patterns & configuration:
- Frontend uses Next.js App Router, shadcn/ui, a layered “pages → components → services → hooks → stores” architecture
- Backend follows an MVC-style organization: routes → controllers → services → models → database
- Dockerfile, Docker Compose, environment examples for containerized dev/prod
- CI/CD and quality config: GitHub Actions workflows, SonarCloud, ESLint, Prettier

##### README for additional insights
- Confirms tech stack: MySQL + Sequelize, Express, Next.js, Webhooks, OAuth, Swagger, Recharts/Chart.js, Google Gemini AI, SonarCloud
- Highlights major features: project/topic management, group assignments, commit & PR tracking, code-quality analysis, real-time notifications, dashboard analytics

##### Elements
- Blue for internal components (frontend/backend)
- Green for data stores (MySQL)
- Orange for external integrations (GitHub, AI)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        NextApp["Next.js App"]:::internal
        subgraph "Client Services & Hooks"
            direction TB
            GHHook["Github Query Hooks"]:::internal
            GHClientService["Github Service"]:::internal
            GeminiClientService["Gemini Service"]:::internal
            ReviewsAIHook["ReviewsAI Query Hooks"]:::internal
            ReviewsAIClientService["ReviewsAI Service"]:::internal
            SocketClient["Socket Service"]:::internal
        end
        NextApp -->|"uses hooks/services"| GHHook
        NextApp -->|uses| GHClientService
        NextApp -->|uses| GeminiClientService
        NextApp -->|uses| ReviewsAIClientService
        NextApp -->|connects via WebSocket| SocketClient
    end

    %% Backend Layer
    subgraph "Backend API Layer"
        direction TB
        ExpressAPI["Express API"]:::internal
        subgraph "Routes"
            direction TB
            GitHubRoute["github.route.ts"]:::internal
            GeminiRoute["gemini.route.ts"]:::internal
            ReviewsAIRoute["reviews_ai.route.ts"]:::internal
        end
        subgraph "Controllers"
            direction TB
            GitHubCtrl["github.controller.ts"]:::internal
            GeminiCtrl["gemini.controller.ts"]:::internal
            ReviewsAICtrl["reviews_ai.controller.ts"]:::internal
        end
        subgraph "Services"
            direction TB
            GitHubService["github-webhook.service.ts & OAuth Service"]:::internal
            GeminiService["gemini.service.ts"]:::internal
            ReviewsAIService["reviews_ai.service.ts"]:::internal
            SocketService["socket.service.ts"]:::internal
        end
        subgraph "Models"
            direction TB
            Models["Sequelize Models"]:::internal
        end
        ExpressAPI -->|routes to| GitHubRoute
        ExpressAPI -->|routes to| GeminiRoute
        ExpressAPI -->|routes to| ReviewsAIRoute
        GitHubRoute -->|calls| GitHubCtrl
        GeminiRoute -->|calls| GeminiCtrl
        ReviewsAIRoute -->|calls| ReviewsAICtrl
        GitHubCtrl -->|uses| GitHubService
        GeminiCtrl -->|uses| GeminiService
        ReviewsAICtrl -->|uses| ReviewsAIService
        ExpressAPI -->|uses| SocketService
        ExpressAPI -->|ORM queries| Models
        %% Swagger
        Swagger["Swagger Spec"]:::internal
        ExpressAPI -->|serves docs| Swagger
    end

    %% Database Layer
    subgraph "Database"
        direction TB
        MySQL["MySQL Database"]:::db
    end
    Models -->|reads/writes| MySQL

    %% External Integrations
    subgraph "External Services"
        direction TB
        GitHub["GitHub API & Webhooks"]:::external
        GeminiAPI["Google Gemini API"]:::external
    end
    ExpressAPI -->|"REST/OAuth"| GitHub
    GitHub -->|"Webhook events (push,pull_request)"| GitHubService
    ExpressAPI -->|"AI requests"| GeminiAPI

    %% Real-time channel
    SocketService -->|push notifications| SocketClient

    %% User browser
    User["User Browser"]:::external
    User -->|"HTTPS"| NextApp
    NextApp -->|"REST/JSON, JWT/OAuth"| ExpressAPI

    %% CI/CD
    CI["GitHub Actions"]:::external
    CI -.->|triggers on PR| GitHub
    CI -.->|status/results| GitHub

    %% Containerization
    subgraph "Containerization"
        direction TB
        DockerCompose["docker-compose.yml"]:::internal
        DockerDev["Dockerfile.dev"]:::internal
        DockerProd["Dockerfile.prod"]:::internal
    end

    %% Click Events
    click NextApp "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/tree/main/src/client"
    click GHHook "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/tree/main/src/client/src/hooks/query-hooks/Github"
    click GHClientService "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/client/src/services/github.service.ts"
    click GeminiClientService "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/client/src/services/gemini.service.ts"
    click ReviewsAIHook "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/tree/main/src/client/src/hooks/query-hooks/ReviewsAI"
    click ReviewsAIClientService "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/client/src/services/reviews_ai.service.ts"
    click SocketClient "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/client/src/services/socket.service.ts"

    click ExpressAPI "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/tree/main/src/server/src"
    click GitHubRoute "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/routes/github.route.ts"
    click GeminiRoute "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/routes/gemini.route.ts"
    click ReviewsAIRoute "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/routes/reviews_ai.route.ts"
    click GitHubCtrl "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/controllers/github.controller.ts"
    click GeminiCtrl "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/controllers/gemini.controller.ts"
    click ReviewsAICtrl "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/controllers/reviews_ai.controller.ts"
    click GitHubService "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/services/github/github-webhook.service.ts"
    click GeminiService "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/services/gemini.service.ts"
    click ReviewsAIService "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/services/reviews_ai.service.ts"
    click SocketService "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/services/socket.service.ts"
    click Models "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/tree/main/src/server/src/models"
    click Swagger "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/src/generated/swagger/swagger.json"
    click MySQL "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/tree/main/src/database"
    click DockerCompose "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/docker-compose.yml"
    click DockerDev "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/Dockerfile.dev"
    click DockerProd "https://github.com/tanmaiii/tn-da21ttb-110121063-dinhtanmai-codeflow/blob/main/src/server/Dockerfile.prod"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef db fill:#E2F0CB,stroke:#5F8727,color:#5F8727
    classDef external fill:#FFE5B4,stroke:#D97706,color:#D97706
    classDef dashed stroke-dasharray: 5 5,opacity:0.7
```
