# team-study-bridge/front-service architecture

> Architecture diagram of the GitHub repository team-study-bridge/front-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/team-study-bridge/front-service
- Repository: https://github.com/team-study-bridge/front-service

## Overview

##### Project Type and Purpose
- This is a single-page application (SPA) frontend for an online education platform (“Aigongbu”).
- Stack: React + TypeScript, Vite for bundling, Tailwind CSS + shadcn-ui for styling, deployed as a Dockerized static service behind Nginx, managed with Helm + ArgoCD on Kubernetes.

##### Main Components
a. Source & CI/CD
- GitHub repository (with `.github/workflows/cl.yml`, `cd.yml`)
- CI jobs: lint/tests → build → Docker image → container registry
b. Containerization & Deployment
- Dockerfile → builds static assets + Nginx
- Helm chart (`helm/front-service`)
- ArgoCD manifests (`argocd/front-app.yaml`)
- Kubernetes cluster: Namespaces, Deployment, Service, Ingress
c. Runtime Frontend Service
- Nginx serving `index.html`, static assets (`public/`, `dist/`)
- Vite dev server (in Local Dev environment)
d. External Dependencies & APIs
- Backend microservices (Auth, Lecture, AI, Payment, Notification, Video, Verification)
- Firebase Messaging (push notifications)
- 3rd-party payment gateway
e. Users & Clients
- Browsers (desktop/mobile) consuming the SPA
- Admin users (through `/admin` pages)
- Instructors, Students

##### Relationships & Data Flows
- Developer pushes code → GitHub Actions CI builds and pushes Docker image.
- CD job triggers ArgoCD to sync Helm release to Kubernetes.
- Kubernetes Ingress routes client traffic via DNS/TLS to the Front-Service.
- Browser fetches static assets; SPA code issues REST/HTTP calls to external backend APIs.
- SPA registers service worker (`public/firebase-messaging-sw.js`) for push notifications.
- Payment flows: SPA ↔ Payment API ↔ 3rd-party gateway.
- AI flows: SPA ↔ AI Chat API → external AI engine.

##### Architectural Patterns & Design Principles
- Single-page application (componentized, with logical feature modules under `src/api`, `src/components`, `src/pages`).
- Containerized static front-end behind reverse proxy (Nginx).
- GitOps deployment (ArgoCD + Helm).
- Clear separation of concerns:
- UI components (`src/components/*`)
- API clients (`src/api/*`)
- Context & hooks (`src/contexts`, `src/hooks`)
- Assets and config (`public/`, `index.html`, `nginx.conf`, `tailwind.config.ts`)

##### Detail Checklist
- [ ] GitHub Actions CI/CD (lint, test, build, push)
- [ ] Docker build context and Nginx config
- [ ] Helm Chart structure and values
- [ ] ArgoCD Application manifest
- [ ] Kubernetes Deployment → Pod → Container
- [ ] Kubernetes Service → Ingress → DNS
- [ ] Browser client → Static assets + API calls
- [ ] External API endpoints (Auth, AI, Lecture, Payment, Noti, Video, Verification)
- [ ] Firebase Messaging integration

## Diagram (Mermaid)

```mermaid
graph TB
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GitHub["GitHub Actions CI/CD"]:::buildDeploy
        ContainerRegistry["Container Registry"]:::buildDeploy
    end

    %% Containerization & Deployment
    subgraph "Container & Deployment" 
        direction TB
        Docker["Docker & Nginx"]:::buildDeploy
        Helm["Helm Chart"]:::buildDeploy
        ArgoCD["ArgoCD"]:::buildDeploy
    end

    %% Runtime Infrastructure
    subgraph "Runtime Infrastructure"
        direction TB
        K8sCluster["Kubernetes Cluster"]:::runtimeInfra
        subgraph "Front-Service Deployment"
            direction TB
            Ingress["Ingress"]:::runtimeInfra
            Service["Service"]:::runtimeInfra
            Deployment["Deployment"]:::runtimeInfra
            Pod["Pod"]:::runtimeInfra
            Nginx["Nginx (Static Server)"]:::runtimeInfra
        end
        LocalDev["Vite Dev Server (Local)"]:::runtimeInfra
    end

    %% Frontend Codebase
    subgraph "Frontend Codebase" 
        direction TB
        UI["UI Components"]:::code
        API["API Clients"]:::code
        Context["Context Providers"]:::code
        Hooks["Custom Hooks"]:::code
        Pages["Pages & Layouts"]:::code
        Entry["Entry Point & Styles"]:::code
        Utils["Utility Modules"]:::code
        Types["Type Definitions"]:::code
        Assets["Static Assets & SW"]:::code
        Config["Tailwind & PostCSS Config"]:::code
    end

    %% External Services
    subgraph "External Services"
        direction TB
        BackendAPIs["Backend Microservices"]:::externalService
        Firebase["Firebase Messaging"]:::externalService
        PaymentGateway["3rd-Party Payment Gateway"]:::externalService
    end

    %% Clients
    subgraph "Clients"
        Browser["User Browser (Desktop/Mobile)"]:::externalService
    end

    %% Connections - CI/CD
    GitHub -->|"build & push image"| ContainerRegistry
    ContainerRegistry -->|"image pull"| Docker
    Docker -->|"package chart"| Helm
    Helm -->|"deploy via"| ArgoCD
    ArgoCD -->|"sync release"| K8sCluster

    %% Connections - Runtime
    Browser -->|"HTTPS"| Ingress
    Ingress --> Service
    Service --> Deployment
    Deployment --> Pod
    Pod --> Nginx
    Nginx -->|"serve assets"| Assets
    Pod -->|"run app code"| Entry

    LocalDev -->|"serve assets & HMR"| Assets

    %% Frontend Codebase Flows
    Entry --> UI
    Entry --> API
    Entry --> Context
    Entry --> Hooks
    Entry --> Pages
    Entry --> Utils
    Entry --> Types
    Entry --> Config

    %% API calls
    API -->|"REST calls"| BackendAPIs
    API -->|"push subscribes"| Firebase
    API -->|"payment requests"| PaymentGateway

    %% Class Definitions
    classDef buildDeploy fill:#FFD580,stroke:#FFB347,color:#000;
    classDef runtimeInfra fill:#B3E5FC,stroke:#81D4FA,color:#000;
    classDef code fill:#E1BEE7,stroke:#CE93D8,color:#000;
    classDef externalService fill:#C8E6C9,stroke:#A5D6A7,color:#000;

    %% Click Events
    click GitHub "https://github.com/team-study-bridge/front-service/blob/main/.github/workflows/cl.yml"
    click GitHub "https://github.com/team-study-bridge/front-service/blob/main/.github/workflows/cd.yml"
    click Docker "https://github.com/team-study-bridge/front-service/tree/main/Dockerfile"
    click Docker "https://github.com/team-study-bridge/front-service/blob/main/entrypoint.sh"
    click Docker "https://github.com/team-study-bridge/front-service/blob/main/nginx.conf"
    click Helm "https://github.com/team-study-bridge/front-service/blob/main/helm/front-service/Chart.yaml"
    click Helm "https://github.com/team-study-bridge/front-service/blob/main/helm/front-service/values.yaml"
    click Helm "https://github.com/team-study-bridge/front-service/blob/main/helm/front-service/templates/deployment.yaml"
    click Helm "https://github.com/team-study-bridge/front-service/blob/main/helm/front-service/templates/service.yaml"
    click Helm "https://github.com/team-study-bridge/front-service/blob/main/helm/front-service/templates/ingress.yaml"
    click ArgoCD "https://github.com/team-study-bridge/front-service/blob/main/argocd/front-app.yaml"
    click LocalDev "https://github.com/team-study-bridge/front-service/blob/main/vite.config.ts"
    click LocalDev "https://github.com/team-study-bridge/front-service/blob/main/tsconfig.app.json"
    click LocalDev "https://github.com/team-study-bridge/front-service/blob/main/package.json"
    click Assets "https://github.com/team-study-bridge/front-service/tree/main/public/"
    click Assets "https://github.com/team-study-bridge/front-service/blob/main/public/firebase-messaging-sw.js"
    click Assets "https://github.com/team-study-bridge/front-service/blob/main/index.html"
    click Assets "https://github.com/team-study-bridge/front-service/blob/main/robots.txt"
    click Config "https://github.com/team-study-bridge/front-service/blob/main/tailwind.config.ts"
    click Config "https://github.com/team-study-bridge/front-service/blob/main/postcss.config.js"
    click API "https://github.com/team-study-bridge/front-service/blob/main/src/api/index.ts"
    click UI "https://github.com/team-study-bridge/front-service/tree/main/src/components/"
    click Context "https://github.com/team-study-bridge/front-service/blob/main/src/contexts/AuthContext.tsx"
    click Hooks "https://github.com/team-study-bridge/front-service/blob/main/src/hooks/use-mobile.tsx"
    click Pages "https://github.com/team-study-bridge/front-service/blob/main/src/pages/Index.tsx"
    click Entry "https://github.com/team-study-bridge/front-service/blob/main/src/main.tsx"
    click Utils "https://github.com/team-study-bridge/front-service/blob/main/src/utils/apiClient.ts"
    click Types "https://github.com/team-study-bridge/front-service/blob/main/src/types/env.d.ts"
```
