# hlum/understandme-server-side architecture

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

- Interactive diagram: https://gitdiagram.com/hlum/understandme-server-side
- Repository: https://github.com/hlum/understandme-server-side

## Overview

#### Purpose and entry points
KnowYourCode is a PHP HTTP API for classroom/homework workflows that generates code-comprehension questions, accepts student answers, scores results, and reports progress. Endpoint scripts under `public/` are the API entry points, e.g. `public/homework/add_homework.php`, `public/questions_choices/v2/get_questions_choices.php`, and `public/result/update_score.php`.

#### Layered application structure
Endpoint scripts delegate business operations to application use cases, which depend on domain entities and repository interfaces rather than concrete storage/services. Core layers are `src/Application/UseCases/`, `src/Domain/Entities/`, and `src/Domain/Repositories/`. Concrete adapters reside in `src/Infrastructure/`.

#### Classroom, identity, and enrollment
Users have roles and participate in classes through enrollment records. Class management and enrollment are exposed independently, forming the authorization/context boundary for teacher/student work. Key paths: `src/Application/UseCases/UserUseCase.php`, `src/Application/UseCases/ClassUseCase.php`, `src/Application/UseCases/StudentClassEnrollmentUseCase.php`.

#### Homework and project lifecycle
Teachers create/update/delete classes, projects, and homework. Homework status is queried per user, and submitted work can be removed. This lifecycle is represented by `Homework`, `Project`, and status-oriented entities/use cases, with APIs under `public/homework/` and `public/project/add_project.php`.

#### Question-generation job pipeline
Question creation is asynchronous: jobs are persisted, a cron container invokes pending-job processing, and retry is exposed via the API. Processing can download source material, extract snippets, and call a question generator before storing questions/choices. Key paths: `Cron/process_pending_jobs.php`, `src/Application/UseCases/ProcessPendingJobsUseCase.php`, `src/Application/UseCases/JobUseCase.php`.

#### Source acquisition and AI generation boundary
Source inputs may come from GitHub or Google Drive through a downloader factory; repository URLs and file types are validated before content reaches generation. Ollama is the external LLM endpoint behind `QuestionGeneratorInterface`; generated questions/choices are then available through versioned retrieval APIs. Key paths: `src/Infrastructure/ExternalServices/DownloaderFactory.php`, `src/Infrastructure/ExternalServices/OllamaQuestionGenerator.php`, `src/Domain/Repositories/QuestionGeneratorInterface.php`.

#### Assessment and reporting
Students submit answers; correct choices, results, average scores, and homework completion status are persisted and queried separately. Score updates are explicit API operations, enabling generation/assessment to remain decoupled. Key paths: `src/Application/UseCases/AnswerUseCase.php`, `src/Application/UseCases/ResultUseCase.php`, `src/Application/UseCases/AverageScoreUseCase.php`.

#### Runtime, persistence, and notifications
Docker Compose runs PHP/Apache, MySQL, and the cron worker; schema initialization is in `mysqlEntry/create_tables.sql`. MySQL repository adapters implement domain persistence contracts. Firebase service-account configuration and FCM-token use cases indicate push notifications through Firebase; Ollama is separately configured by endpoint. Key paths: `docker-compose.yml`, `php/Dockerfile`, `Cron/Dockerfile`.

Main entry points: [`src/Application/UseCases/ProcessPendingJobsUseCase.php`](https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/ProcessPendingJobsUseCase.php) (Pending-job processor), [`src/Application/UseCases/ClassUseCase.php`](https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/ClassUseCase.php) (Identity, classes & enrollment), [`src/Application/UseCases/JobUseCase.php`](https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/JobUseCase.php) (Job management), [`docker-compose.yml`](https://github.com/hlum/understandme-server-side/blob/dev/docker-compose.yml) (Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_homework_api["Homework endpoints<br/>PHP endpoint scripts<br/>[add_homework.php]"]
  node_question_api["Question retrieval API<br/>versioned endpoint"]
  node_result_api["Score update API<br/>endpoint<br/>[update_score.php]"]
  node_project_api["Project API<br/>endpoint<br/>[add_project.php]"]
end

subgraph group_application["Application"]
  node_identity_class["Identity, classes &amp; enrollment<br/>use cases<br/>[ClassUseCase.php]"]
  node_user_use_case["User use case<br/>[UserUseCase.php]"]
  node_enrollment_use_case["Enrollment use case"]
  node_homework_project["Homework &amp; projects<br/>use cases"]
  node_job_use_case["Job management<br/>use case<br/>[JobUseCase.php]"]
  node_job_processor["Pending-job processor<br/>use case"]
  node_assessment["Answers &amp; results<br/>use cases<br/>[AnswerUseCase.php]"]
  node_average_scores["Average scores<br/>use case"]
end

subgraph group_domain["Domain"]
  node_domain_model{{"Entities &amp; repository contracts<br/>domain layer"}}
  node_generator_contract{{"Question generator contract<br/>repository interface"}}
end

subgraph group_infrastructure["Infrastructure"]
  node_mysql_adapters[("MySQL repository adapters<br/>persistence adapters")]
  node_downloader_factory["Source downloader factory<br/>external-service adapter"]
  node_ollama_generator["Ollama generator<br/>LLM adapter"]
  node_firebase["Firebase notifications<br/>push service"]
end

subgraph group_runtime["Runtime"]
  node_cron_worker["Cron job runner<br/>worker container"]
  node_compose["Docker Compose<br/>runtime orchestration<br/>[docker-compose.yml]"]
  node_mysql[("MySQL<br/>database<br/>[create_tables.sql]")]
end

node_homework_api --> node_homework_project
node_project_api --> node_homework_project
node_question_api -->|"retry / retrieve"| node_job_use_case
node_result_api -->|"update score"| node_assessment
node_identity_class -->|"user context"| node_user_use_case
node_identity_class -->|"class membership"| node_enrollment_use_case
node_homework_project -->|"teacher/student context"| node_identity_class
node_homework_project -->|"create generation jobs"| node_job_use_case
node_cron_worker -->|"process pending jobs"| node_job_processor
node_job_processor -->|"loads jobs"| node_job_use_case
node_job_processor -->|"acquire source"| node_downloader_factory
node_job_processor -->|"generate questions"| node_generator_contract
node_ollama_generator -.->|"implements"| node_generator_contract
node_job_processor -->|"stores questions and choices"| node_domain_model
node_assessment -->|"answers and results"| node_domain_model
node_average_scores -->|"queries aggregates"| node_domain_model
node_homework_project -->|"homework and project state"| node_domain_model
node_domain_model -.->|"persistence contracts"| node_mysql_adapters
node_mysql_adapters -->|"persists"| node_mysql
node_compose -->|"runs"| node_cron_worker
node_compose -->|"runs"| node_mysql
node_user_use_case -->|"push notifications"| node_firebase

click node_homework_api "https://github.com/hlum/understandme-server-side/blob/dev/public/homework/add_homework.php"
click node_question_api "https://github.com/hlum/understandme-server-side/blob/dev/public/questions_choices/v2/get_questions_choices.php"
click node_result_api "https://github.com/hlum/understandme-server-side/blob/dev/public/result/update_score.php"
click node_project_api "https://github.com/hlum/understandme-server-side/blob/dev/public/project/add_project.php"
click node_identity_class "https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/ClassUseCase.php"
click node_user_use_case "https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/UserUseCase.php"
click node_enrollment_use_case "https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/StudentClassEnrollmentUseCase.php"
click node_job_use_case "https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/JobUseCase.php"
click node_job_processor "https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/ProcessPendingJobsUseCase.php"
click node_assessment "https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/AnswerUseCase.php"
click node_average_scores "https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/AverageScoreUseCase.php"
click node_generator_contract "https://github.com/hlum/understandme-server-side/blob/dev/src/Domain/Repositories/QuestionGeneratorInterface.php"
click node_downloader_factory "https://github.com/hlum/understandme-server-side/blob/dev/src/Infrastructure/ExternalServices/DownloaderFactory.php"
click node_ollama_generator "https://github.com/hlum/understandme-server-side/blob/dev/src/Infrastructure/ExternalServices/OllamaQuestionGenerator.php"
click node_cron_worker "https://github.com/hlum/understandme-server-side/blob/dev/Cron/process_pending_jobs.php"
click node_compose "https://github.com/hlum/understandme-server-side/blob/dev/docker-compose.yml"
click node_mysql "https://github.com/hlum/understandme-server-side/blob/dev/mysqlEntry/create_tables.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_homework_api,node_question_api,node_result_api,node_project_api toneBlue
class node_identity_class,node_user_use_case,node_enrollment_use_case,node_homework_project,node_job_use_case,node_job_processor,node_assessment,node_average_scores toneAmber
class node_domain_model,node_generator_contract toneMint
class node_mysql_adapters,node_downloader_factory,node_ollama_generator,node_firebase toneRose
class node_cron_worker,node_compose,node_mysql toneIndigo
```

## Components

### HTTP API

- [Homework endpoints](https://github.com/hlum/understandme-server-side/blob/dev/public/homework/add_homework.php): PHP endpoint scripts · Teacher homework lifecycle and status APIs. · `public/homework/add_homework.php`
- [Question retrieval API](https://github.com/hlum/understandme-server-side/blob/dev/public/questions_choices/v2/get_questions_choices.php): versioned endpoint · `public/questions_choices/v2/get_questions_choices.php`
- [Score update API](https://github.com/hlum/understandme-server-side/blob/dev/public/result/update_score.php): endpoint · `public/result/update_score.php`
- [Project API](https://github.com/hlum/understandme-server-side/blob/dev/public/project/add_project.php): endpoint · `public/project/add_project.php`

### Application

- [Identity, classes & enrollment](https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/ClassUseCase.php): use cases · Establishes teacher/student classroom context. · `src/Application/UseCases/ClassUseCase.php`
- [User use case](https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/UserUseCase.php): use case · `src/Application/UseCases/UserUseCase.php`
- [Enrollment use case](https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/StudentClassEnrollmentUseCase.php): use case · `src/Application/UseCases/StudentClassEnrollmentUseCase.php`
- **Homework & projects**: use cases · Manages assignments, projects, submissions, and status.
- [Job management](https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/JobUseCase.php): use case · Persists generation jobs and exposes retry. · `src/Application/UseCases/JobUseCase.php`
- [Pending-job processor](https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/ProcessPendingJobsUseCase.php): use case · Acquires source, generates questions, and stores choices. · `src/Application/UseCases/ProcessPendingJobsUseCase.php`
- [Answers & results](https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/AnswerUseCase.php): use cases · Records answers, scores, completion, and averages. · `src/Application/UseCases/AnswerUseCase.php`
- [Average scores](https://github.com/hlum/understandme-server-side/blob/dev/src/Application/UseCases/AverageScoreUseCase.php): use case · `src/Application/UseCases/AverageScoreUseCase.php`

### Domain

- **Entities & repository contracts**: domain layer · Homework, project, status, result, and question abstractions.
- [Question generator contract](https://github.com/hlum/understandme-server-side/blob/dev/src/Domain/Repositories/QuestionGeneratorInterface.php): repository interface · `src/Domain/Repositories/QuestionGeneratorInterface.php`

### Infrastructure

- **MySQL repository adapters**: persistence adapters · Implements domain persistence contracts.
- [Source downloader factory](https://github.com/hlum/understandme-server-side/blob/dev/src/Infrastructure/ExternalServices/DownloaderFactory.php): external-service adapter · Selects validated GitHub or Google Drive acquisition. · `src/Infrastructure/ExternalServices/DownloaderFactory.php`
- [Ollama generator](https://github.com/hlum/understandme-server-side/blob/dev/src/Infrastructure/ExternalServices/OllamaQuestionGenerator.php): LLM adapter · `src/Infrastructure/ExternalServices/OllamaQuestionGenerator.php`
- **Firebase notifications**: push service · Uses service credentials and FCM tokens.

### Runtime

- [Cron job runner](https://github.com/hlum/understandme-server-side/blob/dev/Cron/process_pending_jobs.php): worker container · Invokes pending-job processing. · `Cron/process_pending_jobs.php`
- [Docker Compose](https://github.com/hlum/understandme-server-side/blob/dev/docker-compose.yml): runtime orchestration · Runs PHP/Apache, MySQL, and cron worker. · `docker-compose.yml`
- [MySQL](https://github.com/hlum/understandme-server-side/blob/dev/mysqlEntry/create_tables.sql): database · Schema initialized for application persistence. · `mysqlEntry/create_tables.sql`

## Connections

- Homework endpoints → Homework & projects
- Project API → Homework & projects
- Question retrieval API → Job management: retry / retrieve
- Score update API → Answers & results: update score
- Identity, classes & enrollment → User use case: user context
- Identity, classes & enrollment → Enrollment use case: class membership
- Homework & projects → Identity, classes & enrollment: teacher/student context
- Homework & projects → Job management: create generation jobs
- Cron job runner → Pending-job processor: process pending jobs
- Pending-job processor → Job management: loads jobs
- Pending-job processor → Source downloader factory: acquire source
- Pending-job processor → Question generator contract: generate questions
- Ollama generator → Question generator contract: implements
- Pending-job processor → Entities & repository contracts: stores questions and choices
- Answers & results → Entities & repository contracts: answers and results
- Average scores → Entities & repository contracts: queries aggregates
- Homework & projects → Entities & repository contracts: homework and project state
- Entities & repository contracts → MySQL repository adapters: persistence contracts
- MySQL repository adapters → MySQL: persists
- Docker Compose → Cron job runner: runs
- Docker Compose → MySQL: runs
- User use case → Firebase notifications: push notifications