hlum/understandme-server-side

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.