ARCHITECTURE.md

Cert Study Lab Architecture

이 파일은 개발 중 빠르게 보는 요약입니다. 자세한 설명은 docs/02_architecture.md를 기준 문서로 봅니다.

Current Shape

Streamlit UI
  -> QuizService / LearningLabService / LearningProgressService
  -> ConceptNoteService / IngestionJobService / QuestionVectorStore
  -> PostgreSQL app DB
  -> Chroma vector index
  -> data/learning_progress.json

Airflow DAGs
  -> PDF ingestion DAG
  -> visual analysis DAG
  -> PostgreSQL app DB

Ollama
  -> text/study assistant
  -> visual question parsing

User-Facing Pages

Keep the first screen light. The home page is a launcher, not a dashboard.

Home
Continue Study
Focus Study
Exam Study
Dashboard
Roadmap
Theory Learning
Learning Quiz
Certification Questions
Wrong/Review
Concept Notes
Processing Status
Content Management
PDF Upload
Exam Overview
AI Index

Study Flow

Continue Study remembers the selected Track and lets the learner keep going instead of stopping at a fixed daily quota.

Track
  -> Certification
  -> Roadmap / Lesson / Quiz / Practice
  -> Certification Questions
  -> Wrong Review
  -> Dashboard

The current active Tracks are:

• Linux -> LFCS
• Azure -> AZ-104
• Tool Docs -> Docs Study

Future Tracks such as Git, Python, SQL, Docker, and Kubernetes are represented in the service data but hidden until ready.

Data Ownership

PostgreSQL
  Canonical app data: questions, answers, attempts, concept notes, ingestion jobs.

Chroma
  Search index: embeddings for similar question and document retrieval.

data/learning_progress.json
  Local learner state: preferred Track, study steps, activity counts.

cert_study_app/demo_data/questions_seed.json
  Deployable seed for Hugging Face Space.

Do not commit runtime data such as local DB files, Chroma indexes, Airflow logs, uploaded PDFs, or private .env files.

Question Statuses

approved
  Stable enough for normal quiz use.

needs_visual
  Requires visual analysis or has a failed visual-analysis result.

needs_review
  Needs human definition or correction.

draft
  Waiting for processing.

rejected
  Excluded from quiz flow.

The quiz repository treats only approved as playable.

Metadata Split

question_type
  How the UI should render the answer interaction.
  Examples: mcq, multi_select, yes_no, hotspot, table_choice, ordering.

category / subcategory / concept_tags
  What the learner is studying.
  Examples: az104_networking / vnet_subnet, az104_compute / vm.

Weak study should prefer subcategory because it is more precise than broad category.

Cleanup Priorities

• Move learning progress from JSON to PostgreSQL when multi-user support starts.
• Keep Streamlit page routing names aligned with user-facing labels.
• Keep long PDF/image processing in Airflow, not inside direct Streamlit requests.
• Add more tests around Track progress, question category filters, and PWA/static file behavior.