How thecodeforgerhq/msf-reasoning-agent works
1. Top-level shape
- Athenaeum is a two-tier system: a Next.js 16 frontend and a FastAPI backend.
- The backend can run fully offline, or it can use optional Microsoft/Azure services plus Groq fallbacks.
- The main runtime contract is HTTP + Server-Sent Events, so the UI receives a live trace of each reasoning turn, not just final text.
2. Backend core: the reasoning pipeline
- The central backend subsystem is app/agent/, which implements a gate → router → answer pipeline.
- Every user turn is processed as a typed stream of events, with separate phases for safety gating, intent routing, grounding, planning, and answer streaming.
- This is the architectural heart of the product: it turns a chat turn into a controlled workflow with visible intermediate states.
3. Safety boundary
- Input safety is enforced before the agent does anything useful.
- The gate is layered: regex pre-filter, deterministic heuristic checks, Prompt Guard, Azure content safety / RAI checks, and additional output guards during streaming.
- Safety is treated as a first-class boundary, not a prompt instruction, and the system distinguishes “unsafe” from “unreachable” provider failures.
4. Routing and multi-intent orchestration
- The router maps a turn to focused agent intents such as recommendation, grounded module Q&A, study planning, practice, evaluation, feedback, and progress checks.
- Compound requests are supported: one message can fan out into an ordered sequence of intents.
- The orchestrator preserves intent order, re-applies per-link guards, and streams the result back in phases.
5. Grounding and answer honesty
- Answers are grounded against the approved course content using either Azure AI Search / Foundry IQ or a deterministic offline lexical retriever.
- If grounding is weak or missing, the system re-dispatches once with stricter sourcing and adds a disclaimer instead of pretending certainty.
- This boundary keeps the assistant tied to the repository’s curated learning corpus rather than free-form generation.
6. Learning domain and content model
- The curated learning material lives in ayanakoji/athenaeum/content/, organized as a catalog of verticals → courses → modules.
- catalog/ loads that content and exposes it to the reasoning agents as the canonical course graph.
- The repo’s design assumes the catalog is authoritative: recommendations, citations, and navigation all depend on it.
7. Courses, chats, and learner state
- The backend models “a chat as a course”: course rows hold the conversation plus staging state.
- Progress is not stored as a simple flag; it is derived from assessments and current course structure.
- Course-related flows live under app/courses/ and include chat, practice, assessments, skill checks, feedback, and progression views.
8. Assessments as a separate bounded system
- Authored assessment banks are isolated from learner state in a separate SQLite database.
- The bank files in ayanakoji/assessments/banks/ are validated against a JSON schema and seeded through backend tooling.
- Assessment execution includes quiz generation, oral evaluation, grading, and validation logic, with support for Azure Blob mirroring when cloud credentials exist.
9. Manager Insights boundary
- app/manager/ provides a separate aggregate-only surface for team leads.
- It consumes only team-level rollups and synthetic Work IQ data, not individual learner details, so the data-flow boundary prevents per-person leakage.
- The manager UI is guarded and reuses the same safety/trace style as learner chat, but with aggregate snapshots instead of personal learning data.
10. Work IQ and notifications
- app/workiq/ serves a deterministic, synthetic organizational calendar and work-pattern model used by study planning and manager analytics.
- app/notifications/ maintains a background tick that emits reminders, deadlines, streak events, and deduplicated notifications.
- These are supporting services rather than the main interaction loop, but they feed the planning and engagement surfaces.
11. Persistence and data boundaries
- The repo intentionally separates mutable learner workspace from authored assets:
- athenaeum.db for learner/course state
- assessments.db for authored banks and attempts
- WAL mode and idempotent schema setup support simple deployment and offline use.
- The local content corpus, assessment banks, and synthetic Work IQ data are all repo-owned artifacts, which keeps the app deterministic and reproducible.
12. Frontend architecture
- The frontend is a Next.js App Router app with distinct surfaces for login, learner workspace, course chat, module views, assessments, reviews, and the manager dashboard.
- It parses SSE events into UI components such as traces, practice cards, skill-gate cards, plans, suggestions, and blocked/error states.
- The UX is built around inspectability: users can see the trace of the agent’s reasoning, not just the final answer.
13. External services and fallback strategy
- Optional cloud dependencies include Azure OpenAI, Azure AI Search, Azure AI Evaluation, Azure Content Safety, and Azure Blob Storage.
- Groq provides fallback LLMs and jailbreak classification when configured.
- The system is designed to degrade to a deterministic offline path when cloud credentials are missing or services are unavailable.
14. Quality, evaluation, and deployment
- The backend includes a substantial tests/ suite, plus a dedicated red-team / audit harness in agent_audit/ for live and offline evaluation.
- CI covers backend checks, frontend checks, Playwright E2E, and secret scanning.
- Deployment is split: backend on Render, frontend on Vercel, with local PM2 support for running both services together.
15. What to draw in an architecture diagram
- The most important boxes are: frontend SSE client, FastAPI backend, agent pipeline, content/catalog store, assessments store, Work IQ/notifications, and the optional Azure/Groq cloud column.
- The key arrows are:
- browser → backend via HTTP/SSE
- backend → catalog/content and databases
- agent pipeline → grounding/safety/LLM services
- manager insights → aggregate snapshots only
- frontend ← streamed trace/events
- The main architectural boundary is between curated, deterministic repository data and optional cloud inference services.
Main entry points: orchestrator.py Agent Flow · main.py FastAPI App · router_agent.py Router · grounding.py Grounding
Components 25
Frontend
Next.js App Router UI with SSE-driven learner and manager experiences
- Browser · Learner and manager entry point
ayanakoji/frontend/src/app/page.tsx - SSE UI · Streams reasoning traces into chat, practice, and manager views
ayanakoji/frontend/src/components/chat/pipeline-trace.tsx - Workspace · Learner workspace, navigation, and course surfaces
ayanakoji/frontend/src/components/workspace/workspace-chrome.tsx - Manager UI · Aggregate insights and guarded manager workspace
ayanakoji/frontend/src/components/manager/insights-dashboard.tsx - API Client · Fetches backend data and opens chat/manager flows
ayanakoji/frontend/src/lib/api.ts
Backend
FastAPI services, agent pipeline, courses, assessments, and supporting APIs
- FastAPI App · Backend entrypoint and route assembly
ayanakoji/backend/app/main.py - Agent Flow · Gate → router → grounding → answer streaming pipeline
ayanakoji/backend/app/agent/orchestrator.py - Safety Gate · Input filtering and policy checks before agent work
ayanakoji/backend/app/agent/gate.py - Router · Maps turns to ordered intents and fan-out workflows
ayanakoji/backend/app/agent/router_agent.py - Grounding · Approved-corpus retrieval and citation verification
ayanakoji/backend/app/agent/grounding.py - Answer Stream · Streams final responses and trace events back to the UI
ayanakoji/backend/app/agent/answer.py - Courses API · Chat, practice, assessments, skill checks, and feedback flows
ayanakoji/backend/app/courses/router.py - Assessments API · Authored assessment banks, grading, validation, and seed flows
ayanakoji/backend/app/assessments/router.py - Catalog API · Loads authoritative course graph and content metadata
ayanakoji/backend/app/catalog/router.py - Manager API · Team-level rollups and synthetic insights only
ayanakoji/backend/app/manager/router.py - Work IQ · Deterministic organizational calendar and work-pattern model
ayanakoji/backend/app/workiq/router.py - Notifications · Reminder, deadline, and streak notification loop
ayanakoji/backend/app/notifications/background.py
Repository Data
Curated course content, assessment banks, and synthetic work data
- Content Corpus · Verticals, courses, and modules used as authoritative learning material
ayanakoji/athenaeum/content/_catalog.json - Assessment Banks · Validated authored assessment banks and attempts
ayanakoji/assessments/schema/bank.schema.json - Work IQ Data · Synthetic work-pattern source data for planning and analytics
ayanakoji/backend/app/data/work_iq.json
Optional Cloud
External inference, safety, search, and storage services used when configured
- Azure Services · OpenAI, Search, Safety, Foundry IQ, Evaluation, and Blob Storage
ayanakoji/backend/app/foundry.py - Groq Fallback · Fallback LLM and jailbreak classification when configured
ayanakoji/backend/app/agent/llm.py
Ops & Quality
Tests, audit harnesses, and deployment/CI surfaces
- Audit Suite · Offline and live red-team evaluation harness
ayanakoji/backend/agent_audit/harness.py - Test Suite · Backend and frontend checks, including E2E coverage
ayanakoji/backend/tests/test_agent_orchestrator.py - CI / Deploy · GitHub Actions, Render, Vercel, and local process orchestration
.github/workflows/ci.yml
Connections 28
- Browser → API Client: uses · UI invokes backend APIs and chat routes
- API Client → FastAPI App: http+sse · Client reaches FastAPI over HTTP and Server-Sent Events
- FastAPI App → SSE UI: streams · Backend emits trace and answer events for live rendering
- FastAPI App → Agent Flow: turns · Chat turns enter the controlled reasoning pipeline
- Agent Flow → Safety Gate: gates · Every turn is filtered before other work begins
- Agent Flow → Router: routes · Intent selection and ordered orchestration
- Agent Flow → Grounding: grounds · Retrieval and citation verification against approved content
- Agent Flow → Answer Stream: streams · Final response and intermediate events are streamed out
- Router → Courses API: dispatches · Course chat, practice, study plans, and skill checks
- Router → Assessments API: dispatches · Assessment generation, grading, and review flows
- Router → Manager API: dispatches · Manager-intent requests go to aggregate-only views
- Courses API → Catalog API: reads · Course flows depend on canonical course and module metadata
- Courses API → Content Corpus: uses · Learner navigation and recommendations rely on curated corpus
- Assessments API → Assessment Banks: reads · Banks are validated and loaded from authored artifacts
- Manager API → Work IQ: summaries · Manager insights use team-level and synthetic work data
- Work IQ → Work IQ Data: loads · Deterministic synthetic organizational source data
- Notifications → Courses API: nudges · Background reminders and streak events support learner flow
- Grounding → Catalog API: retrieves · Content graph is the canonical grounding source
- Grounding → Content Corpus: corpus · Offline lexical retrieval from repo-owned content
- Grounding → Azure Services: optional · Azure AI Search / Foundry IQ can replace or augment offline retrieval
- Safety Gate → Azure Services: checks · Azure content safety and RAI checks when configured
- Agent Flow → Groq Fallback: fallback · Fallback LLM and classification path when cloud services are unavailable
- Assessments API → Azure Services: mirror · Assessment artifacts can mirror to Azure Blob storage
- Audit Suite → Agent Flow: evaluates · Red-team and live audits exercise the agent pipeline
- Test Suite → FastAPI App: verifies · Automated tests cover backend contracts and behavior
- CI / Deploy → Test Suite: runs · CI executes backend, frontend, E2E, and scanning checks
- CI / Deploy → FastAPI App: deploys · Backend deployment target and runtime packaging
- CI / Deploy → Workspace: deploys · Frontend deployment target and app delivery