How 142spp/qi4u_in_pnu_team8 works
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.