# 142spp/qi4u_in_pnu_team8 architecture

> Architecture diagram of the GitHub repository 142spp/qi4u_in_pnu_team8, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/142spp/qi4u_in_pnu_team8
- Repository: https://github.com/142spp/qi4u_in_pnu_team8

## Overview

This is a **containerized full-stack web service** for **university timetable optimization**. The “core value” is the **optimization pipeline**: user preferences + constraints → **QUBO modeling** → **Simulated/Quantum-Annealing-like solver** → optimized timetable, exposed via **FastAPI** and rendered in a **Next.js** UI.

- A **Next.js frontend** that gathers constraints/preferences and visualizes schedules
- A **FastAPI backend** that:
- loads lecture data (CSV/Pandas)
- creates and runs optimization jobs asynchronously via **BackgroundTasks**
- stores task state/results **in-memory**
- The **polling-based async workflow** (`task_id` + `/status` polling)
- Docker Compose topology (two containers)

##### Frontend (`front/`)
- **Next.js App Router**: `front/src/app/*`
- `layout.tsx`, `page.tsx`, `providers.tsx` (global providers: Zustand / Query client likely)
- **UI components**: `front/src/components/*`
- `OptimizationPanel.tsx` (inputs: required courses, credit target, preferences)
- `OptimizationDetails.tsx` (shows solver status/result metadata)
- `TimetableView.tsx`, `MiniTimetable.tsx`, `TimetableCardsRow.tsx` (visualization)
- `LectureList.tsx` (list filtering + debounce performance)
- **Client state**: `front/src/store/useLectureStore.ts` (Zustand)
- **Server state / async**: (per README) **TanStack Query** (not obvious in tree, but stated; likely wired in `providers.tsx`)
- **Time parsing**: `front/src/lib/timeParser.ts` (important: converts “금 09:00(50)(외부)” into normalized timeslots for UI and/or request payload)

##### Backend (`back/`)
- **FastAPI entrypoint**: `back/app/main.py`
- **API layer**: `back/app/api.py` (your REST endpoints live here)
- **Core loading**: `back/app/core/loader.py` (loads lecture dataset)
- **Services layer**:
- `services/task_manager.py` (in-memory task registry; statuses PENDING/PROCESSING/SUCCESS/FAILURE)
- `services/bqm_builder.py` (builds QUBO/BQM model from constraints)
- `services/quantum_optimizer.py` (runs dimod simulated annealing / solver)
- **Data**: `back/data/lectures.csv` (the “database substitute”)
- **Utils**: `back/app/utils/time_utils.py` (backend time normalization/parsing)
- **No DB/ORM**: in-memory dicts + Pandas per README

##### Infrastructure (repo root)
- `docker-compose.yml` orchestrates **front container + back container**
- `front/Dockerfile`, `back/Dockerfile` define runtime images

##### API Router (`api.py`)
- Endpoints:
- `POST /api/optimize` (returns `task_id`)
- `GET /api/tasks/{task_id}` or similar (status polling)
- (Possibly) `GET /api/lectures` (list/filters) if implemented

##### Task Manager (`services/task_manager.py`)
- Responsibilities:
- Create task ID
- Store status + progress + result payload
- Update status transitions: PENDING → PROCESSING → SUCCESS/FAILURE

##### Optimization Orchestrator (logical) (may be in `api.py` or service)
- Kicks off `BackgroundTasks.add_task(...)`
- Calls builder + solver; writes result back to Task Manager

##### BQM/QUBO Builder (`services/bqm_builder.py`)
- Converts:
- selected courses / constraints / soft preferences
- into QUBO weights (penalties) / BQM model

##### Quantum Optimizer (`services/quantum_optimizer.py`)
- Runs dimod simulated annealing
- Returns best sample(s) / objective score / chosen lecture set

##### Loader (`core/loader.py`)
- Loads lectures.csv into Pandas dataframe or normalized structure used by API & solver

##### Time Utils (`utils/time_utils.py`)
- Backend-side timeslot conversion / conflict detection input for constraints

- `api.py` → `task_manager.create_task()` → returns `task_id`
- `api.py` → `BackgroundTasks` kicks `run_optimization(task_id, payload)`
- `run_optimization` → `loader` (if needed for lecture universe)
- `run_optimization` → `bqm_builder.build(payload, lectures)` → BQM/QUBO
- `run_optimization` → `quantum_optimizer.solve(bqm)` → solution
- `run_optimization` → `task_manager.update(task_id, status=SUCCESS, result=...)`

**Components (use real code anchors)**
- Page/App: `front/src/app/page.tsx`
- State: `useLectureStore.ts` (Zustand)
- Server-state: TanStack Query (wired via `providers.tsx`)
- UI: `OptimizationPanel.tsx`, `OptimizationDetails.tsx`, `TimetableView.tsx`
- Utility: `timeParser.ts`

**Flow**
##### Frontend starts polling every ~1s
- `GET /api/tasks/{task_id}` → receives status + partial/final result
##### On SUCCESS
- update Zustand store with final timetable
- `TimetableView` renders blocks
- `OptimizationDetails` shows objective/weights/status history

- endpoint names
- payload types (“preferences/constraints”, “task_id”, “status/result”)

##### What to emphasize as “architectural patterns”

- **Async job execution without a queue**: FastAPI `BackgroundTasks` inside the API process
- Pros/cons annotation (optional but useful): in-memory, not durable, process restart loses tasks
- **Polling instead of push**: client polls task status every second
- **In-memory state store**: Python dict-based task registry instead of DB/Redis
- **Algorithmic pipeline separation**: builder (modeling) vs solver (optimization)
- **Dataset-as-source-of-truth**: `lectures.csv` + Pandas loader (no DB schema)

##### Labels
- Use **exact runtime + framework** labels:
- “Next.js (App Router)”
- “FastAPI (Uvicorn)”
- “dimod (Simulated Annealing sampler)”
- “BackgroundTasks (in-process async)”
- “lectures.csv (Pandas-loaded)”
- “Task Manager — `back/app/services/task_manager.py`”

- Docker Compose boundary with **two services** (front/back)
- Backend:
- `api.py` endpoints
- `BackgroundTasks` asynchronous execution
- `task_manager.py` in-memory state + task lifecycle
- `bqm_builder.py` and `quantum_optimizer.py` separation
- `lectures.csv` + loader
- Frontend:
- Optimization input panel
- Polling loop (TanStack Query)
- Zustand store update
- Timetable rendering components
- `timeParser.ts` as a distinct “parsing/normalization” step

- `POST /api/optimize` → returns task_id
- polling loop → success → UI update

This set captures the essential architecture without overthinking: it “separates into as many components as possible” while staying anchored to the actual repo structure.

## Diagram (Mermaid)

```mermaid
flowchart TB

%% =========================
%% Diagram A — System Context (C4-L1)
%% =========================
subgraph A["A) System Context (C4-L1)"]
  direction TB

  U["User (Browser)"]:::external
  FE_CTX["Next.js Web App<br/>(App Router UI)"]:::frontend
  BE_CTX["FastAPI Backend API<br/>(Uvicorn)"]:::backend

  CSV_CTX[("lectures.csv<br/>(Pandas-loaded)")]:::datastore
  DIMOD_CTX["dimod<br/>(Simulated Annealing sampler)"]:::externalAlgo

  U -->|"HTTP(S)"| FE_CTX
  FE_CTX -->|"HTTP JSON<br/>/api/*"| BE_CTX
  BE_CTX -->|"read_csv()"| CSV_CTX
  BE_CTX -->|"in-process call"| DIMOD_CTX
end

%% =========================
%% Diagram B — Container Diagram (C4-L2, Docker Compose)
%% =========================
subgraph B["B) Container Diagram (C4-L2) — Docker Compose"]
  direction TB

  subgraph DC_STACK["docker-compose.yml (Two Services)"]
    direction TB

    BROWSER["Browser<br/>localhost"]:::external

    subgraph FE_SVC["frontend service (container)"]
      direction TB
      FE_DOCK["Next.js (Node runtime)<br/>:3000"]:::frontend
      FE_APP["App Router<br/>front/src/app/*"]:::frontend
      FE_DOCK -->|"serves"| FE_APP
    end

    subgraph BE_SVC["backend service (container)"]
      direction TB
      BE_DOCK["FastAPI (Uvicorn)<br/>:8000"]:::backend
      BE_API["REST API<br/>back/app/api.py"]:::backend
      BE_TASKS["BackgroundTasks<br/>(in-process async)"]:::backend
      BE_TASKSTORE["In-memory Task Store<br/>(Python dict; no Redis/DB)"]:::backend
      BE_DATA[("lectures.csv<br/>back/data/lectures.csv")]:::datastore

      BE_DOCK -->|"routes"| BE_API
      BE_API -.->|"schedules"| BE_TASKS
      BE_API -->|"create/update status"| BE_TASKSTORE
      BE_DOCK -->|"file access"| BE_DATA
    end

    BROWSER -->|"GET http://localhost:3000"| FE_DOCK
    FE_DOCK -->|"fetch http://localhost:8000/api/*"| BE_DOCK

    NOTE_NODB["Constraint:<br/>No external DB/ORM<br/>No Redis/Celery<br/>Tasks lost on restart"]:::note
    BE_TASKSTORE -.->|"non-durable"| NOTE_NODB
  end
end

%% =========================
%% Diagram C — Backend Component Diagram (C4-L3)
%% =========================
subgraph C["C) Backend Components (C4-L3) — Optimization Pipeline + Task State"]
  direction TB

  CLIENT_FE["Frontend Client<br/>(Next.js)"]:::frontend

  subgraph BE_BOUNDARY["FastAPI Backend (back/app/*)"]
    direction TB

    BE_MAIN["App Entrypoint<br/>main.py"]:::backend
    API_ROUTER["API Router<br/>api.py<br/>- POST /api/optimize<br/>- GET /api/tasks/{task_id}<br/>- (optional) GET /api/lectures"]:::backend

    BG["BackgroundTasks<br/>(in-process async)"]:::backend
    TM["Task Manager<br/>services/task_manager.py<br/>PENDING→PROCESSING→SUCCESS/FAILURE"]:::backend
    ORCH["Optimization Orchestrator<br/>(logical; in api.py task fn)"]:::backend

    LOADER["Lecture Loader<br/>core/loader.py<br/>(Pandas ingestion)"]:::backend
    TIMEU["Time Utils<br/>utils/time_utils.py<br/>(normalize/slots/conflicts)"]:::backend

    BQM["BQM/QUBO Builder<br/>services/bqm_builder.py<br/>(constraints→model)"]:::algo
    SOLVER["Quantum Optimizer<br/>services/quantum_optimizer.py<br/>(dimod simulated annealing)"]:::algo

    CSV[("lectures.csv<br/>back/data/lectures.csv")]:::datastore
    DIMOD["dimod library<br/>(SA sampler)"]:::externalAlgo

    BE_MAIN -->|"includes"| API_ROUTER

    CLIENT_FE -->|"POST /api/optimize<br/>preferences/constraints"| API_ROUTER
    API_ROUTER -->|"create_task()"| TM
    API_ROUTER -.->|"add_task(run_optimization)"| BG
    BG -.->|"executes"| ORCH

    ORCH -->|"update(status=PROCESSING)"| TM
    ORCH -->|"load lectures"| LOADER
    LOADER -->|"read_csv()"| CSV
    ORCH -->|"normalize times"| TIMEU
    ORCH -->|"build(model)"| BQM
    BQM -->|"solve(model)"| SOLVER
    SOLVER -->|"calls"| DIMOD
    ORCH -->|"update(status=SUCCESS/FAILURE,result)"| TM

    CLIENT_FE -->|"GET /api/tasks/{task_id}<br/>(poll ~1s)"| API_ROUTER
    API_ROUTER -->|"get_task_status/result"| TM
  end
end

%% =========================
%% Diagram D — Frontend Data Flow (Polling UX)
%% =========================
subgraph D["D) Frontend Data Flow — Async Polling Pattern"]
  direction TB

  USER_UI["User (Browser UI)"]:::external

  subgraph FE_BOUNDARY["Next.js Frontend (front/src/*)"]
    direction TB

    PAGE["Page / Entry UI<br/>front/src/app/page.tsx"]:::frontend
    LAYOUT["Layout<br/>front/src/app/layout.tsx"]:::frontend
    PROV["Providers<br/>front/src/app/providers.tsx<br/>(TanStack Query client)"]:::frontend

    PANEL["OptimizationPanel<br/>front/src/components/OptimizationPanel.tsx"]:::frontend
    DETAILS["OptimizationDetails<br/>front/src/components/OptimizationDetails.tsx"]:::frontend

    STORE["Zustand Store<br/>front/src/store/useLectureStore.ts"]:::frontend

    TP["Time Parser<br/>front/src/lib/timeParser.ts"]:::frontend
    TU["Time Utils<br/>front/src/utils/timeUtils.ts"]:::frontend

    LECTURES["LectureList<br/>front/src/components/LectureList.tsx<br/>(filter/debounce)"]:::frontend

    VIEW["TimetableView<br/>front/src/components/TimetableView.tsx"]:::frontend
    MINI["MiniTimetable<br/>front/src/components/MiniTimetable.tsx"]:::frontend
    CARDS["TimetableCardsRow<br/>front/src/components/TimetableCardsRow.tsx"]:::frontend

    QUERY["TanStack Query<br/>(polling + caching)"]:::frontend
  end

  API["FastAPI API<br/>POST /api/optimize<br/>GET /api/tasks/{task_id}"]:::backend

  USER_UI -->|"interacts"| PAGE
  LAYOUT -->|"wraps"| PROV
  PROV -->|"provides"| QUERY

  PAGE -->|"renders"| PANEL
  PAGE -->|"renders"| DETAILS
  PAGE -->|"renders"| LECTURES
  PAGE -->|"renders"| VIEW
  VIEW -->|"includes"| MINI
  VIEW -->|"includes"| CARDS

  PANEL -->|"updates selections"| STORE
  LECTURES -->|"updates selection/filter"| STORE

  PANEL -->|"normalize payload"| TP
  TP -->|"helpers"| TU

  PANEL -->|"mutation: POST /api/optimize<br/>(payload: prefs/constraints)"| QUERY
  QUERY -->|"HTTP JSON"| API
  API -->|"returns {task_id}"| QUERY

  QUERY -->|"poll (refetchInterval ~1s)<br/>GET /api/tasks/{task_id}"| API
  API -->|"status + result"| QUERY

  QUERY -->|"on SUCCESS: set timetable"| STORE
  STORE -->|"state drives"| VIEW
  QUERY -->|"status/metadata"| DETAILS
end

%% =========================
%% Click Events (from component_mapping)
%% =========================
click FE_APP "https://github.com/142spp/qi4u_in_pnu_team8/tree/main/front/src/app/"
click LAYOUT "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/app/layout.tsx"
click PAGE "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/app/page.tsx"
click PROV "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/app/providers.tsx"

click PANEL "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/components/OptimizationPanel.tsx"
click DETAILS "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/components/OptimizationDetails.tsx"
click VIEW "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/components/TimetableView.tsx"
click MINI "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/components/MiniTimetable.tsx"
click CARDS "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/components/TimetableCardsRow.tsx"
click LECTURES "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/components/LectureList.tsx"

click STORE "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/store/useLectureStore.ts"
click TP "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/lib/timeParser.ts"
click TU "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/front/src/utils/timeUtils.ts"

click BE_MAIN "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/back/app/main.py"
click API_ROUTER "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/back/app/api.py"
click LOADER "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/back/app/core/loader.py"
click TM "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/back/app/services/task_manager.py"
click BQM "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/back/app/services/bqm_builder.py"
click SOLVER "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/back/app/services/quantum_optimizer.py"
click TIMEU "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/back/app/utils/time_utils.py"
click CSV "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/back/data/lectures.csv"

click FE_DOCK "https://github.com/142spp/qi4u_in_pnu_team8/tree/main/front/Dockerfile"
click BE_DOCK "https://github.com/142spp/qi4u_in_pnu_team8/tree/main/back/Dockerfile"

DC["docker-compose.yml"]:::infra
DC -->|"defines"| FE_DOCK
DC -->|"defines"| BE_DOCK
click DC "https://github.com/142spp/qi4u_in_pnu_team8/blob/main/docker-compose.yml"

%% =========================
%% Styles
%% =========================
classDef external fill:#ffffff,stroke:#374151,stroke-width:1px,color:#111827
classDef frontend fill:#dbeafe,stroke:#1d4ed8,stroke-width:1px,color:#0f172a
classDef backend fill:#dcfce7,stroke:#16a34a,stroke-width:1px,color:#052e16
classDef algo fill:#ffedd5,stroke:#ea580c,stroke-width:1px,color:#7c2d12
classDef externalAlgo fill:#fee2e2,stroke:#ef4444,stroke-width:1px,color:#7f1d1d
classDef datastore fill:#e5e7eb,stroke:#6b7280,stroke-width:1px,color:#111827
classDef infra fill:#ede9fe,stroke:#6d28d9,stroke-width:1px,color:#2e1065
classDef note fill:#f3f4f6,stroke:#9ca3af,stroke-dasharray:3 3,color:#111827
```
