# jiyan-0525/goalcoach architecture

> Architecture diagram of the GitHub repository jiyan-0525/goalcoach, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jiyan-0525/goalcoach
- Repository: https://github.com/jiyan-0525/goalcoach

## Overview

GoalCoach is an adaptive Chinese-learning coach built around a state-driven loop: learners set goals, receive a curriculum plan, study through teaching actions, submit answers, and have progress updated to guide future planning. The graph includes the web/API entry points, deterministic orchestration and progress rules, AI teaching/planning/grading, grounded curriculum and learner persistence, plus the CLI capability documented in the README. Edge evidence is limited to the supplied excerpts, SOURCE INDEX references, and README; unsampled subsystem links are omitted where their callers are not shown.

Main entry points: [`src/goalcoach/application/orchestrator.py`](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/application/orchestrator.py) (Event orchestrator), [`apps/api/main.py`](https://github.com/jiyan-0525/goalcoach/blob/main/apps/api/main.py) (FastAPI gateway), [`src/goalcoach/infrastructure/llm/pydantic_ai_models.py`](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/llm/pydantic_ai_models.py) (PydanticAI model gateway), [`apps/web/src/App.tsx`](https://github.com/jiyan-0525/goalcoach/blob/main/apps/web/src/App.tsx) (Learning web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner interfaces"]
  node_web["Learning web app<br/>[App.tsx]"]
  node_learning_views["Plan and learning views"]
  node_retention_view["Retention visualizer"]
  node_cli["Terminal harness"]
end

subgraph group_gateway["API and orchestration"]
  node_api["FastAPI gateway<br/>[main.py]"]
  node_event_routes["Learning event routes<br/>[learning_loop.py]"]
  node_learner_routes["Learner routes<br/>[learning.py]"]
  node_orchestrator["Event orchestrator<br/>[orchestrator.py]"]
  node_agent_history["Agent history<br/>[agent_history.py]"]
end

subgraph group_learning["Learning engine"]
  node_planning["Planning agent<br/>[planning_agent.py]"]
  node_teaching["Teaching agent<br/>[teaching_agent.py]"]
  node_grader["Grading component"]
  node_progress_service["Progress service"]
  node_progress_reducer["Progress reducer"]
  node_domain_models["Learning state models<br/>[models.py]"]
end

subgraph group_storage["Curriculum and state"]
  node_content_service["Curriculum content service<br/>[content_service.py]"]
  node_content_repo["Curriculum repository<br/>[repositories.py]"]
  node_curriculum_db[("Curriculum database<br/>[database.py]")]
  node_learner_repo["Learner repository<br/>[repositories.py]"]
  node_learner_db[("Learner state database<br/>[database.py]")]
end

subgraph group_platform["Model and observability"]
  node_model_gateway["PydanticAI model gateway"]
  node_observability["Request observability<br/>[observability.py]"]
end

node_learner(("Learner"))
node_model_services["Hosted or local models"]

node_learner -->|"uses"| node_web
node_web -->|"sends events"| node_api
node_api -->|"routes requests"| node_event_routes
node_api -->|"routes requests"| node_learner_routes
node_event_routes -->|"dispatches events"| node_orchestrator
node_learner_routes -->|"uses"| node_orchestrator
node_orchestrator -->|"dispatches goals"| node_planning
node_orchestrator -->|"dispatches sessions"| node_teaching
node_orchestrator -->|"dispatches answers"| node_grader
node_orchestrator -->|"updates progress"| node_progress_service
node_progress_service -->|"reduces progress"| node_progress_reducer
node_orchestrator -->|"loads and saves"| node_learner_repo
node_progress_service -->|"persists state"| node_learner_repo
node_learner_repo -->|"reads and writes"| node_learner_db
node_planning -->|"queries curriculum"| node_content_service
node_teaching -->|"fetches examples"| node_content_service
node_content_service -->|"queries content"| node_content_repo
node_content_repo -.->|"reads content"| node_curriculum_db
node_planning -->|"requests reasoning"| node_model_gateway
node_teaching -->|"requests reasoning"| node_model_gateway
node_grader -->|"evaluates answers"| node_model_gateway
node_model_gateway -.->|"uses model"| node_model_services
node_web -->|"renders views"| node_learning_views
node_learning_views -.->|"renders retention"| node_retention_view
node_learner -.->|"uses"| node_cli
node_event_routes -->|"uses history"| node_agent_history
node_api -->|"installs middleware"| node_observability

click node_web "https://github.com/jiyan-0525/goalcoach/blob/main/apps/web/src/App.tsx"
click node_learning_views "https://github.com/jiyan-0525/goalcoach/tree/main/apps/web/src/components"
click node_retention_view "https://github.com/jiyan-0525/goalcoach/blob/main/apps/web/src/components/RetentionVisualizer.tsx"
click node_cli "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/agents/terminal_harness.py"
click node_api "https://github.com/jiyan-0525/goalcoach/blob/main/apps/api/main.py"
click node_event_routes "https://github.com/jiyan-0525/goalcoach/blob/main/apps/api/routes/learning_loop.py"
click node_learner_routes "https://github.com/jiyan-0525/goalcoach/blob/main/apps/api/routes/learning.py"
click node_orchestrator "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/application/orchestrator.py"
click node_agent_history "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/application/agent_history.py"
click node_planning "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/agents/planning_agent.py"
click node_teaching "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/agents/teaching_agent.py"
click node_grader "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/agents/grader_component.py"
click node_progress_service "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/application/progress_service.py"
click node_progress_reducer "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/application/progress_reducer.py"
click node_domain_models "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/domain/models.py"
click node_content_service "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/persistence/content_service.py"
click node_content_repo "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/persistence/repositories.py"
click node_curriculum_db "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/persistence/database.py"
click node_learner_repo "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/persistence/repositories.py"
click node_learner_db "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/persistence/database.py"
click node_model_gateway "https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/llm/pydantic_ai_models.py"
click node_observability "https://github.com/jiyan-0525/goalcoach/blob/main/apps/api/middleware/observability.py"

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_web,node_learning_views,node_retention_view,node_cli toneBlue
class node_api,node_event_routes,node_learner_routes,node_orchestrator,node_agent_history toneAmber
class node_planning,node_teaching,node_grader,node_progress_service,node_progress_reducer,node_domain_models toneMint
class node_content_service,node_content_repo,node_curriculum_db,node_learner_repo,node_learner_db toneRose
class node_model_gateway,node_observability,node_learner,node_model_services toneIndigo
```

## Components

### Learner interfaces

- [Learning web app](https://github.com/jiyan-0525/goalcoach/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Plan and learning views](https://github.com/jiyan-0525/goalcoach/tree/main/apps/web/src/components): `apps/web/src/components`
- [Retention visualizer](https://github.com/jiyan-0525/goalcoach/blob/main/apps/web/src/components/RetentionVisualizer.tsx): `apps/web/src/components/RetentionVisualizer.tsx`
- [Terminal harness](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/agents/terminal_harness.py): `src/goalcoach/agents/terminal_harness.py`

### API and orchestration

- [FastAPI gateway](https://github.com/jiyan-0525/goalcoach/blob/main/apps/api/main.py): `apps/api/main.py`
- [Learning event routes](https://github.com/jiyan-0525/goalcoach/blob/main/apps/api/routes/learning_loop.py): `apps/api/routes/learning_loop.py`
- [Learner routes](https://github.com/jiyan-0525/goalcoach/blob/main/apps/api/routes/learning.py): `apps/api/routes/learning.py`
- [Event orchestrator](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/application/orchestrator.py): `src/goalcoach/application/orchestrator.py`
- [Agent history](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/application/agent_history.py): `src/goalcoach/application/agent_history.py`

### Learning engine

- [Planning agent](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/agents/planning_agent.py): `src/goalcoach/agents/planning_agent.py`
- [Teaching agent](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/agents/teaching_agent.py): `src/goalcoach/agents/teaching_agent.py`
- [Grading component](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/agents/grader_component.py): `src/goalcoach/agents/grader_component.py`
- [Progress service](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/application/progress_service.py): `src/goalcoach/application/progress_service.py`
- [Progress reducer](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/application/progress_reducer.py): `src/goalcoach/application/progress_reducer.py`
- [Learning state models](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/domain/models.py): `src/goalcoach/domain/models.py`

### Curriculum and state

- [Curriculum content service](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/persistence/content_service.py): `src/goalcoach/infrastructure/persistence/content_service.py`
- [Curriculum repository](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/persistence/repositories.py): `src/goalcoach/infrastructure/persistence/repositories.py`
- [Curriculum database](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/persistence/database.py): `src/goalcoach/infrastructure/persistence/database.py`
- [Learner repository](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/persistence/repositories.py): `src/goalcoach/infrastructure/persistence/repositories.py`
- [Learner state database](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/persistence/database.py): `src/goalcoach/infrastructure/persistence/database.py`

### Model and observability

- [PydanticAI model gateway](https://github.com/jiyan-0525/goalcoach/blob/main/src/goalcoach/infrastructure/llm/pydantic_ai_models.py): `src/goalcoach/infrastructure/llm/pydantic_ai_models.py`
- [Request observability](https://github.com/jiyan-0525/goalcoach/blob/main/apps/api/middleware/observability.py): `apps/api/middleware/observability.py`

### Other components

- **Learner**
- **Hosted or local models**

## Connections

- Learner → Learning web app: uses (evidence: `apps/web/src/App.tsx`)
- Learning web app → FastAPI gateway: sends events (evidence: `apps/web/src/App.tsx`)
- FastAPI gateway → Learning event routes: routes requests (evidence: `apps/api/main.py`)
- FastAPI gateway → Learner routes: routes requests (evidence: `apps/api/main.py`)
- Learning event routes → Event orchestrator: dispatches events (evidence: `apps/api/routes/learning_loop.py`)
- Learner routes → Event orchestrator: uses (evidence: `apps/api/routes/learning.py`)
- Event orchestrator → Planning agent: dispatches goals (evidence: `src/goalcoach/application/orchestrator.py`)
- Event orchestrator → Teaching agent: dispatches sessions (evidence: `src/goalcoach/application/orchestrator.py`)
- Event orchestrator → Grading component: dispatches answers (evidence: `src/goalcoach/application/orchestrator.py`)
- Event orchestrator → Progress service: updates progress (evidence: `src/goalcoach/application/orchestrator.py`)
- Progress service → Progress reducer: reduces progress (evidence: `src/goalcoach/application/progress_service.py`)
- Event orchestrator → Learner repository: loads and saves (evidence: `src/goalcoach/application/orchestrator.py`)
- Progress service → Learner repository: persists state (evidence: `src/goalcoach/application/progress_service.py`)
- Learner repository → Learner state database: reads and writes (evidence: `src/goalcoach/infrastructure/persistence/repositories.py`)
- Planning agent → Curriculum content service: queries curriculum (evidence: `src/goalcoach/agents/planning_agent.py`)
- Teaching agent → Curriculum content service: fetches examples (evidence: `src/goalcoach/agents/teaching_agent.py`)
- Curriculum content service → Curriculum repository: queries content (evidence: `src/goalcoach/infrastructure/persistence/content_service.py`)
- Curriculum repository → Curriculum database: reads content
- Planning agent → PydanticAI model gateway: requests reasoning (evidence: `src/goalcoach/agents/planning_agent.py`)
- Teaching agent → PydanticAI model gateway: requests reasoning (evidence: `src/goalcoach/agents/teaching_agent.py`)
- Grading component → PydanticAI model gateway: evaluates answers (evidence: `src/goalcoach/agents/grader_component.py`)
- PydanticAI model gateway → Hosted or local models: uses model
- Learning web app → Plan and learning views: renders views (evidence: `apps/web/src/App.tsx`)
- Plan and learning views → Retention visualizer: renders retention
- Learner → Terminal harness: uses
- Learning event routes → Agent history: uses history (evidence: `apps/api/routes/learning_loop.py`)
- FastAPI gateway → Request observability: installs middleware (evidence: `apps/api/main.py`)
