# zapataisra/homeschool-backend architecture

> Architecture diagram of the GitHub repository zapataisra/homeschool-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zapataisra/homeschool-backend
- Repository: https://github.com/zapataisra/homeschool-backend

## Overview

HomeschoolAI is a family-oriented homeschool learning platform: adults create family and child profiles, children use guided curriculum chat, and the application retrieves SEP curriculum material to ground learning sessions. The runtime also includes search, critical math evaluation and XP, family progress, authentication, and Stripe billing. A separate Python adapter set supports curriculum ingestion and RAG preparation. The main runtime flow is supported by sampled chat and search code; several API routes and Python integrations are unsampled, so their links are left unasserted.

Main entry points: [`HomeschoolAI.Api/Program.cs`](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Program.cs) (API host), [`HomeschoolAI.Application/Search/SearchService.cs`](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Application/Search/SearchService.cs) (Search orchestration), [`HomeschoolAI.Application/Chat/ChatService.cs`](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Application/Chat/ChatService.cs) (Chat orchestration), [`web/src/App.tsx`](https://github.com/zapataisra/homeschool-backend/blob/master/web/src/App.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learning experience"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_learning_ui["Learning session UI"]
  node_chat_api["Chat API<br/>[AgentEndpoints.cs]"]
  node_chat["Chat orchestration<br/>[ChatService.cs]"]
  node_agent["LLM completion"]
  node_evaluation["Critical evaluation"]
  node_math["Math validation and XP<br/>[MathValidator.cs]"]
end

subgraph group_retrieval["Curriculum retrieval"]
  node_search_api["Search API<br/>[SearchEndpoints.cs]"]
  node_search["Search orchestration<br/>[SearchService.cs]"]
  node_embedder["Query embeddings"]
  node_repository["Hybrid retrieval"]
  node_curriculum_store[("Curriculum vectors<br/>[EmbeddingChunk.cs]")]
  node_ingestion["Curriculum ingestion<br/>[ingestion.py]"]
end

subgraph group_family["Family and progress"]
  node_family_ui["Family dashboard"]
  node_family_api["Family API<br/>[FamilyEndpoints.cs]"]
  node_identity["Identity and families"]
  node_family_service["Family service"]
  node_learning_data["Learning and progress"]
  node_app_db[("Family database<br/>[AppDbContext.cs]")]
end

subgraph group_platform["Runtime and integrations"]
  node_api_host["API host<br/>[Program.cs]"]
  node_payments["Stripe payments"]
  node_payment_api["Payment API"]
  node_email["Email delivery<br/>[SmtpEmailSender.cs]"]
end

node_learner(("Learner"))

node_learner -.->|"uses"| node_webapp
node_webapp -->|"renders"| node_learning_ui
node_learning_ui -.->|"requests sessions"| node_chat_api
node_chat_api -.->|"dispatches"| node_chat
node_chat -->|"requests completion"| node_agent
node_chat -->|"retrieves curriculum"| node_search
node_chat -->|"records activity"| node_learning_data
node_evaluation -->|"requests assessment"| node_agent
node_evaluation -.->|"validates and scores"| node_math
node_search_api -.->|"dispatches"| node_search
node_search -->|"embeds query"| node_embedder
node_search -->|"searches"| node_repository
node_repository -->|"queries"| node_curriculum_store
node_ingestion -.->|"populates"| node_curriculum_store
node_webapp -->|"renders"| node_family_ui
node_family_ui -.->|"requests family data"| node_family_api
node_family_api -.->|"dispatches"| node_family_service
node_family_service -->|"reads family data"| node_app_db
node_identity -->|"reads and writes"| node_app_db
node_learning_data -->|"reads and writes progress"| node_app_db
node_api_host -->|"registers"| node_search
node_api_host -->|"registers"| node_embedder
node_api_host -->|"registers"| node_repository
node_api_host -->|"registers"| node_payments
node_payment_api -.->|"dispatches"| node_payments
node_api_host -->|"configures"| node_email

click node_webapp "https://github.com/zapataisra/homeschool-backend/blob/master/web/src/App.tsx"
click node_learning_ui "https://github.com/zapataisra/homeschool-backend/blob/master/web/src/features/chat/useLearningSession.ts"
click node_chat_api "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Endpoints/AgentEndpoints.cs"
click node_chat "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Application/Chat/ChatService.cs"
click node_agent "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/SemanticKernel/SemanticKernelAgentCompletionService.cs"
click node_evaluation "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Application/Evaluation/CriticalEvaluationService.cs"
click node_math "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Application/Validation/MathValidator.cs"
click node_search_api "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Endpoints/SearchEndpoints.cs"
click node_search "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Application/Search/SearchService.cs"
click node_embedder "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Embedding/OnnxQueryEmbedder.cs"
click node_repository "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Persistence/EmbeddingRepository.cs"
click node_curriculum_store "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Domain/Entities/EmbeddingChunk.cs"
click node_ingestion "https://github.com/zapataisra/homeschool-backend/blob/master/app/adapters/ingestion.py"
click node_family_ui "https://github.com/zapataisra/homeschool-backend/blob/master/web/src/features/family/FamilyDashboard.tsx"
click node_family_api "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Endpoints/FamilyEndpoints.cs"
click node_identity "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Identity/IdentityAuthService.cs"
click node_family_service "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Identity/IdentityFamilyService.cs"
click node_learning_data "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Learning/ChildLearningRepository.cs"
click node_app_db "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Identity/AppDbContext.cs"
click node_api_host "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Program.cs"
click node_payments "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Payments/StripePaymentService.cs"
click node_payment_api "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Endpoints/PaymentEndpoints.cs"
click node_email "https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Email/SmtpEmailSender.cs"

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_webapp,node_learning_ui,node_chat_api,node_chat,node_agent,node_evaluation,node_math toneBlue
class node_search_api,node_search,node_embedder,node_repository,node_curriculum_store,node_ingestion toneAmber
class node_family_ui,node_family_api,node_identity,node_family_service,node_learning_data,node_app_db toneMint
class node_api_host,node_payments,node_payment_api,node_email toneRose
class node_learner toneIndigo
```

## Components

### Learning experience

- [Web application](https://github.com/zapataisra/homeschool-backend/blob/master/web/src/App.tsx): `web/src/App.tsx`
- [Learning session UI](https://github.com/zapataisra/homeschool-backend/blob/master/web/src/features/chat/useLearningSession.ts): `web/src/features/chat/useLearningSession.ts`
- [Chat API](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Endpoints/AgentEndpoints.cs): `HomeschoolAI.Api/Endpoints/AgentEndpoints.cs`
- [Chat orchestration](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Application/Chat/ChatService.cs): `HomeschoolAI.Application/Chat/ChatService.cs`
- [LLM completion](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/SemanticKernel/SemanticKernelAgentCompletionService.cs): `HomeschoolAI.Adapters/SemanticKernel/SemanticKernelAgentCompletionService.cs`
- [Critical evaluation](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Application/Evaluation/CriticalEvaluationService.cs): `HomeschoolAI.Application/Evaluation/CriticalEvaluationService.cs`
- [Math validation and XP](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Application/Validation/MathValidator.cs): `HomeschoolAI.Application/Validation/MathValidator.cs`

### Curriculum retrieval

- [Search API](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Endpoints/SearchEndpoints.cs): `HomeschoolAI.Api/Endpoints/SearchEndpoints.cs`
- [Search orchestration](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Application/Search/SearchService.cs): `HomeschoolAI.Application/Search/SearchService.cs`
- [Query embeddings](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Embedding/OnnxQueryEmbedder.cs): `HomeschoolAI.Adapters/Embedding/OnnxQueryEmbedder.cs`
- [Hybrid retrieval](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Persistence/EmbeddingRepository.cs): `HomeschoolAI.Adapters/Persistence/EmbeddingRepository.cs`
- [Curriculum vectors](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Domain/Entities/EmbeddingChunk.cs): `HomeschoolAI.Domain/Entities/EmbeddingChunk.cs`
- [Curriculum ingestion](https://github.com/zapataisra/homeschool-backend/blob/master/app/adapters/ingestion.py): `app/adapters/ingestion.py`

### Family and progress

- [Family dashboard](https://github.com/zapataisra/homeschool-backend/blob/master/web/src/features/family/FamilyDashboard.tsx): `web/src/features/family/FamilyDashboard.tsx`
- [Family API](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Endpoints/FamilyEndpoints.cs): `HomeschoolAI.Api/Endpoints/FamilyEndpoints.cs`
- [Identity and families](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Identity/IdentityAuthService.cs): `HomeschoolAI.Adapters/Identity/IdentityAuthService.cs`
- [Family service](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Identity/IdentityFamilyService.cs): `HomeschoolAI.Adapters/Identity/IdentityFamilyService.cs`
- [Learning and progress](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Learning/ChildLearningRepository.cs): `HomeschoolAI.Adapters/Learning/ChildLearningRepository.cs`
- [Family database](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Identity/AppDbContext.cs): `HomeschoolAI.Adapters/Identity/AppDbContext.cs`

### Runtime and integrations

- [API host](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Program.cs): `HomeschoolAI.Api/Program.cs`
- [Stripe payments](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Payments/StripePaymentService.cs): `HomeschoolAI.Adapters/Payments/StripePaymentService.cs`
- [Payment API](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Api/Endpoints/PaymentEndpoints.cs): `HomeschoolAI.Api/Endpoints/PaymentEndpoints.cs`
- [Email delivery](https://github.com/zapataisra/homeschool-backend/blob/master/HomeschoolAI.Adapters/Email/SmtpEmailSender.cs): `HomeschoolAI.Adapters/Email/SmtpEmailSender.cs`

### Other components

- **Learner**

## Connections

- Learner → Web application: uses
- Web application → Learning session UI: renders (evidence: `web/src/App.tsx`)
- Learning session UI → Chat API: requests sessions
- Chat API → Chat orchestration: dispatches
- Chat orchestration → LLM completion: requests completion (evidence: `HomeschoolAI.Application/Chat/ChatService.cs`)
- Chat orchestration → Search orchestration: retrieves curriculum (evidence: `HomeschoolAI.Application/Chat/ChatService.cs`)
- Chat orchestration → Learning and progress: records activity (evidence: `HomeschoolAI.Application/Chat/ChatService.cs`)
- Critical evaluation → LLM completion: requests assessment (evidence: `HomeschoolAI.Application/Evaluation/CriticalEvaluationService.cs`)
- Critical evaluation → Math validation and XP: validates and scores
- Search API → Search orchestration: dispatches
- Search orchestration → Query embeddings: embeds query (evidence: `HomeschoolAI.Application/Search/SearchService.cs`)
- Search orchestration → Hybrid retrieval: searches (evidence: `HomeschoolAI.Application/Search/SearchService.cs`)
- Hybrid retrieval → Curriculum vectors: queries (evidence: `HomeschoolAI.Adapters/Persistence/EmbeddingRepository.cs`)
- Curriculum ingestion → Curriculum vectors: populates
- Web application → Family dashboard: renders (evidence: `web/src/App.tsx`)
- Family dashboard → Family API: requests family data
- Family API → Family service: dispatches
- Family service → Family database: reads family data (evidence: `HomeschoolAI.Adapters/Identity/IdentityFamilyService.cs`)
- Identity and families → Family database: reads and writes (evidence: `HomeschoolAI.Adapters/Identity/IdentityAuthService.cs`)
- Learning and progress → Family database: reads and writes progress (evidence: `HomeschoolAI.Adapters/Learning/ChildLearningRepository.cs`)
- API host → Search orchestration: registers (evidence: `HomeschoolAI.Api/Program.cs`)
- API host → Query embeddings: registers (evidence: `HomeschoolAI.Api/Program.cs`)
- API host → Hybrid retrieval: registers (evidence: `HomeschoolAI.Api/Program.cs`)
- API host → Stripe payments: registers (evidence: `HomeschoolAI.Api/Program.cs`)
- Payment API → Stripe payments: dispatches
- API host → Email delivery: configures (evidence: `HomeschoolAI.Api/Program.cs`)
