How jiyan-0525/goalcoach works
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: orchestrator.py Event orchestrator · main.py FastAPI gateway · pydantic_ai_models.py PydanticAI model gateway · App.tsx Learning web app
Components 24
Learner interfaces
- Learning web app
apps/web/src/App.tsx - Plan and learning views
apps/web/src/components - Retention visualizer
apps/web/src/components/RetentionVisualizer.tsx - Terminal harness
src/goalcoach/agents/terminal_harness.py
API and orchestration
- FastAPI gateway
apps/api/main.py - Learning event routes
apps/api/routes/learning_loop.py - Learner routes
apps/api/routes/learning.py - Event orchestrator
src/goalcoach/application/orchestrator.py - Agent history
src/goalcoach/application/agent_history.py
Learning engine
- Planning agent
src/goalcoach/agents/planning_agent.py - Teaching agent
src/goalcoach/agents/teaching_agent.py - Grading component
src/goalcoach/agents/grader_component.py - Progress service
src/goalcoach/application/progress_service.py - Progress reducer
src/goalcoach/application/progress_reducer.py - Learning state models
src/goalcoach/domain/models.py
Curriculum and state
- Curriculum content service
src/goalcoach/infrastructure/persistence/content_service.py - Curriculum repository
src/goalcoach/infrastructure/persistence/repositories.py - Curriculum database
src/goalcoach/infrastructure/persistence/database.py - Learner repository
src/goalcoach/infrastructure/persistence/repositories.py - Learner state database
src/goalcoach/infrastructure/persistence/database.py
Model and observability
- PydanticAI model gateway
src/goalcoach/infrastructure/llm/pydantic_ai_models.py - Request observability
apps/api/middleware/observability.py
Other components
- Learner
- Hosted or local models
Connections 27
- Learner → Learning web app: uses
apps/web/src/App.tsx - Learning web app → FastAPI gateway: sends events
apps/web/src/App.tsx - FastAPI gateway → Learning event routes: routes requests
apps/api/main.py - FastAPI gateway → Learner routes: routes requests
apps/api/main.py - Learning event routes → Event orchestrator: dispatches events
apps/api/routes/learning_loop.py - Learner routes → Event orchestrator: uses
apps/api/routes/learning.py - Event orchestrator → Planning agent: dispatches goals
src/goalcoach/application/orchestrator.py - Event orchestrator → Teaching agent: dispatches sessions
src/goalcoach/application/orchestrator.py - Event orchestrator → Grading component: dispatches answers
src/goalcoach/application/orchestrator.py - Event orchestrator → Progress service: updates progress
src/goalcoach/application/orchestrator.py - Progress service → Progress reducer: reduces progress
src/goalcoach/application/progress_service.py - Event orchestrator → Learner repository: loads and saves
src/goalcoach/application/orchestrator.py - Progress service → Learner repository: persists state
src/goalcoach/application/progress_service.py - Learner repository → Learner state database: reads and writes
src/goalcoach/infrastructure/persistence/repositories.py - Planning agent → Curriculum content service: queries curriculum
src/goalcoach/agents/planning_agent.py - Teaching agent → Curriculum content service: fetches examples
src/goalcoach/agents/teaching_agent.py - Curriculum content service → Curriculum repository: queries content
src/goalcoach/infrastructure/persistence/content_service.py - Curriculum repository → Curriculum database: reads content
- Planning agent → PydanticAI model gateway: requests reasoning
src/goalcoach/agents/planning_agent.py - Teaching agent → PydanticAI model gateway: requests reasoning
src/goalcoach/agents/teaching_agent.py - Grading component → PydanticAI model gateway: evaluates answers
src/goalcoach/agents/grader_component.py - PydanticAI model gateway → Hosted or local models: uses model
- Learning web app → Plan and learning views: renders views
apps/web/src/App.tsx - Plan and learning views → Retention visualizer: renders retention
- Learner → Terminal harness: uses
- Learning event routes → Agent history: uses history
apps/api/routes/learning_loop.py - FastAPI gateway → Request observability: installs middleware
apps/api/main.py