# hoangm416/lung-cancer-management architecture

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

- Interactive diagram: https://gitdiagram.com/hoangm416/lung-cancer-management
- Repository: https://github.com/hoangm416/lung-cancer-management

## Overview

##### Project Type and Purpose
- Full-stack web application for clinical/omics data analysis and visualization.
- Frontend (React + Vite + TypeScript + Tailwind) presents charts and tables.
- Backend (Node.js + Express + TypeScript) exposes RESTful APIs for user, record, research, analytics.
- Uses Supabase for authentication and a relational database (Postgres or similar) for persistence.

##### Main Components
A. Client / Browser
- Loads the React single-page app (index.html + static assets).
- Interacts via HTTP(S) with backend APIs and Supabase.
B. Frontend Application
- Vite dev/build server or static container.
- React components, routes (AppRoutes.tsx), UI (charts, tables, forms).
- Supabase client for sign-in, auth callbacks, ProtectedRoute wrapper.
- Static data files under public/data consumed for Kaplan–Meier plots.
C. Backend Application
- Express server (index.ts) in a Docker container.
- Controllers (AnalyticsController, RecordController, ResearchController, UserController).
- Models mapping to DB tables (user, record, research, gene, omics, etc.).
- Routes connecting endpoints to controllers.
- Auth middleware guarding protected endpoints.
- Utility scripts for data processing.
D. Database
- Relational DB (e.g. Postgres) storing users, records, research entries, omics results.
E. External Services
- Supabase Auth / DB if fully managed.
- Docker-Compose orchestrates frontend, backend, and database containers.

##### Relationships and Data Flows
1) User → Browser → React UI → Supabase Auth (login/register)
2) React UI → REST requests → Backend Routes → Controllers → Models → Database → Controllers → JSON responses → React UI
3) React UI loads static JSON/TSV files for exploratory charts directly from its public folder.
4) Docker-Compose manages network: frontend ↔ backend ↔ database.

##### Architectural Patterns & Design Principles
- MVC-style layering on the backend (Routes → Controllers → Models).
- Component-driven UI in the frontend (atomic UI, chart/table components).
- Separation of concerns: auth, API logic, data models, UI, static assets.
- Use of middleware for cross-cutting (authentication).
- Containerization (Docker) for consistent development/deployment.

##### Technologies & Frameworks
- Frontend: React, Vite, TypeScript, Tailwind CSS, Supabase JS SDK, Chart libraries (e.g., your custom BarChart, KaplanMeierChart).
- Backend: Node.js, Express, TypeScript, Docker, ts-node, dotenv.
- Database: PostgreSQL (or Supabase-managed DB).
- DevOps: Docker, Docker‐Compose.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Network
    subgraph "Client Network"
        direction TB
        Browser["Client / Browser"]:::frontend
        SupabaseAuth["Supabase Auth"]:::external
    end

    %% Docker Compose Orchestration
    subgraph "Docker-Compose (docker-compose.yml)"
        direction TB
        %% Frontend Container
        subgraph "Frontend Container (port 3000)"
            direction TB
            FrontendApp["Frontend Application"]:::frontend
            FE_Docker["Frontend Dockerfile"]:::backend
            subgraph "Frontend Source"
                direction TB
                Main["main.tsx"]:::frontend
                Routes["AppRoutes.tsx"]:::frontend
                Components["UI Components"]:::frontend
                Pages["Page Views"]:::frontend
                SupabaseClient["Supabase Client & Auth Flow"]:::frontend
                ProtectedRoute["ProtectedRoute Wrapper"]:::frontend
                StaticData["Static Data (public/data)"]:::frontend
                Styles["Global Styles & Config"]:::frontend
            end
        end

        %% Backend Container
        subgraph "Backend Container (port 5000)"
            direction TB
            BackendAPI["Backend API (Express)"]:::backend
            BE_Docker["Backend Dockerfile"]:::backend
            subgraph "Backend Source"
                direction TB
                Index["index.ts"]:::backend
                RoutesBG["API Routes"]:::backend
                Controllers["API Controllers"]:::backend
                Models["Data Models"]:::backend
                Middleware["Authentication Middleware"]:::backend
                Utils["Utility Scripts"]:::backend
            end
        end

        %% Database
        DB["PostgreSQL Database"]:::db
    end

    %% Data Flows
    Browser -->|"load index.html"| FrontendApp
    FrontendApp -->|"fetch static assets"| StaticData
    FrontendApp -->|"login/register"| SupabaseAuth
    FrontendApp -->|"REST API calls"| BackendAPI
    BackendAPI -->|"routes"| RoutesBG
    RoutesBG -->|"controllers"| Controllers
    Controllers -->|"models"| Models
    Controllers -->|"utils"| Utils
    BackendAPI -->|"auth middleware"| Middleware
    BackendAPI -->|"DB queries"| DB
    FrontendApp -->|"protected routing"| ProtectedRoute

    %% Click Events
    click Browser "https://github.com/hoangm416/lung-cancer-management/blob/main/frontend/index.html"
    click FrontendApp "https://github.com/hoangm416/lung-cancer-management/tree/main/frontend/src"
    click Main "https://github.com/hoangm416/lung-cancer-management/blob/main/frontend/src/main.tsx"
    click Routes "https://github.com/hoangm416/lung-cancer-management/blob/main/frontend/src/AppRoutes.tsx"
    click Components "https://github.com/hoangm416/lung-cancer-management/tree/main/frontend/src/components"
    click Pages "https://github.com/hoangm416/lung-cancer-management/tree/main/frontend/src/pages"
    click SupabaseClient "https://github.com/hoangm416/lung-cancer-management/blob/main/frontend/src/lib/supabase/client.ts"
    click SupabaseClient "https://github.com/hoangm416/lung-cancer-management/blob/main/frontend/src/lib/supabase/unified.ts"
    click ProtectedRoute "https://github.com/hoangm416/lung-cancer-management/blob/main/frontend/src/auth/ProtectedRoute.tsx"
    click StaticData "https://github.com/hoangm416/lung-cancer-management/tree/main/frontend/public/data"
    click Styles "https://github.com/hoangm416/lung-cancer-management/blob/main/frontend/src/global.css"
    click Styles "https://github.com/hoangm416/lung-cancer-management/blob/main/tailwind.config.js"
    click FE_Docker "https://github.com/hoangm416/lung-cancer-management/tree/main/frontend/Dockerfile"
    click BackendAPI "https://github.com/hoangm416/lung-cancer-management/blob/main/backend/src/index.ts"
    click Index "https://github.com/hoangm416/lung-cancer-management/blob/main/backend/src/index.ts"
    click RoutesBG "https://github.com/hoangm416/lung-cancer-management/tree/main/backend/src/routes"
    click Controllers "https://github.com/hoangm416/lung-cancer-management/tree/main/backend/src/controllers"
    click Models "https://github.com/hoangm416/lung-cancer-management/tree/main/backend/src/models"
    click Middleware "https://github.com/hoangm416/lung-cancer-management/blob/main/backend/src/middleware/auth.ts"
    click Utils "https://github.com/hoangm416/lung-cancer-management/blob/main/backend/src/utils/scripts.ts"
    click BE_Docker "https://github.com/hoangm416/lung-cancer-management/tree/main/backend/Dockerfile"
    click DB "https://github.com/hoangm416/lung-cancer-management/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#21618C,stroke-width:2px
    classDef backend fill:#A9DFBF,stroke:#196F3D,stroke-width:2px
    classDef db fill:#F9E79F,stroke:#B7950B,stroke-width:2px
    classDef external fill:#D5DBDB,stroke:#424949,stroke-width:2px
```
