# aspirant200715/cogni architecture

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

- Interactive diagram: https://gitdiagram.com/aspirant200715/cogni
- Repository: https://github.com/aspirant200715/cogni

## Overview

#### Purpose and Entry Points
Cogni is a full-stack metacognitive study companion: it records learning interactions, retrieves learner history, applies specialized reasoning engines, and presents adaptive coaching plus memory analytics. Backend startup is `backend/run.py`, which serves the FastAPI application in `backend/app/main.py`; API documentation is exposed through FastAPI. The Next.js client enters through `frontend/src/app/page.tsx` and calls the backend via `frontend/src/services/api.ts`.

#### Client Application
The frontend is a single Next.js/React TypeScript experience that selects study modes and renders backend results. It centralizes API interaction in `frontend/src/services/api.ts`, while memory-oriented visualizations are separated into `frontend/src/components/memory/MemoryTimeline.tsx`, `frontend/src/components/memory/ConfidenceGraph.tsx`, and `frontend/src/components/memory/CognitiveSummary.tsx`. Tailwind/custom UI primitives support presentation, but coaching logic remains server-side.

#### HTTP/API Boundary
FastAPI route modules define the public contract, with direct and `/api/*` aliases. Functional boundaries are study/quiz logging in `backend/app/routes/study_routes.py`, multi-turn Socratic interactions in `backend/app/routes/socratic_routes.py`, predictive/connection/roadmap insights in `backend/app/routes/insights_routes.py`, and memory retrieval, summaries, and PDF export in `backend/app/routes/memory_routes.py`. Feedback and health are isolated in `backend/app/routes/feedback_routes.py` and `backend/app/routes/health_routes.py`.

#### Orchestration and Cognitive Engines
`backend/app/core/orchestrator.py` coordinates the hybrid strategy: deterministic responses where possible, memory grounding, LLM enrichment, and graceful fallback. Specialized engines represent the main reasoning stages:
- historical confusion analysis: `backend/app/engines/archaeology_engine.py`
- misconception questioning and follow-ups: `backend/app/engines/socratic_engine.py`
- likely struggle prediction: `backend/app/engines/shadow_engine.py`
- cross-topic conceptual links: `backend/app/engines/resonance_engine.py`
- personalized strategy and guided roadmap generation: `backend/app/engines/contagion_engine.py`
- learner self-analysis/reflection: `backend/app/engines/reflection_engine.py`

Routes should delegate domain reasoning to these engines rather than embed it in HTTP handlers.

#### Memory and Personalization Flow
Learning logs, Socratic exchanges, feedback, and study signals feed a user-scoped memory layer. `backend/app/services/hindsight_service.py` is the external persistent-memory integration; `backend/app/services/local_memory_fallback.py` provides resilient local storage when that dependency is unavailable, with local artifacts under `backend/_local_memory/`. `backend/app/services/memory_analytics_service.py` converts recalled history into timeline, confidence, and profile-oriented outputs. Shared payload/domain types reside in `backend/app/models/memory_types.py`.

#### Generation, Summaries, and Output
Engines use `backend/app/services/llm_service.py` to access Groq-hosted LLM reasoning and `backend/app/services/prompt_template_service.py` for prompt construction. Their important failure boundary is upstream AI availability: responses must remain useful through deterministic logic and memory/local fallbacks. `backend/app/services/summary_service.py` produces study summaries and downloadable PDF output, using ReportLab with FPDF2 fallback as documented.

#### Runtime and External Infrastructure
Backend runtime is Python 3.8+, FastAPI, and Pydantic, with dependencies declared in `backend/requirements.txt` and environment expectations in `backend/.env.example`. The frontend requires Node.js 18+, Next.js, React, and Tailwind (`frontend/package.json`). Material external services are Groq (requires `GROQ_API_KEY`) and Hindsight memory; the deployed frontend is hosted on Vercel per the project documentation.

Main entry points: [`backend/app/main.py`](https://github.com/aspirant200715/cogni/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/core/orchestrator.py`](https://github.com/aspirant200715/cogni/blob/main/backend/app/core/orchestrator.py) (Hybrid orchestrator), [`backend/app/services/hindsight_service.py`](https://github.com/aspirant200715/cogni/blob/main/backend/app/services/hindsight_service.py) (Hindsight integration), [`backend/app/routes/memory_routes.py`](https://github.com/aspirant200715/cogni/blob/main/backend/app/routes/memory_routes.py) (Memory routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js Client"]
  node_web_page["Study UI<br/>Next.js page<br/>[page.tsx]"]
  node_api_client["API client<br/>TypeScript service<br/>[api.ts]"]
  node_memory_views["Memory visualizations<br/>React components<br/>[MemoryTimeline.tsx]"]
end

subgraph group_api["FastAPI API"]
  node_backend_entry["Backend startup<br/>Python entry point<br/>[run.py]"]
  node_fastapi_app["FastAPI application<br/>API runtime<br/>[main.py]"]
  node_study_routes["Study &amp; quiz routes<br/>route module<br/>[study_routes.py]"]
  node_socratic_routes["Socratic routes<br/>route module<br/>[socratic_routes.py]"]
  node_insight_routes["Insight routes<br/>route module<br/>[insights_routes.py]"]
  node_memory_routes["Memory routes<br/>route module<br/>[memory_routes.py]"]
end

subgraph group_reasoning["Cognitive Reasoning"]
  node_orchestrator{{"Hybrid orchestrator<br/>coordination service<br/>[orchestrator.py]"}}
  node_reasoning_engines["Specialized engines<br/>reasoning engines"]
  node_llm_service["LLM service<br/>generation service<br/>[llm_service.py]"]
  node_prompt_service["Prompt templates<br/>prompt service"]
end

subgraph group_memory["Memory &amp; Output"]
  node_hindsight["Hindsight integration<br/>persistent memory service"]
  node_local_memory[("Local memory fallback<br/>resilient storage")]
  node_memory_analytics["Memory analytics<br/>analytics service"]
  node_summary_service["Summary &amp; PDF output<br/>output service<br/>[summary_service.py]"]
  node_memory_types["Memory domain types<br/>payload models<br/>[memory_types.py]"]
end

subgraph group_external["External Services"]
  node_groq(("Groq<br/>hosted LLM"))
  node_hindsight_external(("Hindsight memory<br/>external memory"))
end

node_web_page -->|"uses"| node_api_client
node_api_client -->|"HTTP requests"| node_fastapi_app
node_fastapi_app -->|"serves"| node_study_routes
node_fastapi_app -->|"serves"| node_socratic_routes
node_fastapi_app -->|"serves"| node_insight_routes
node_fastapi_app -->|"serves"| node_memory_routes
node_backend_entry -->|"starts"| node_fastapi_app
node_study_routes -->|"logs and coaches"| node_orchestrator
node_socratic_routes -->|"multi-turn guidance"| node_orchestrator
node_insight_routes -->|"insights"| node_orchestrator
node_memory_routes -->|"retrieval analytics"| node_memory_analytics
node_memory_routes -->|"summaries and export"| node_summary_service
node_orchestrator -->|"delegates reasoning"| node_reasoning_engines
node_orchestrator -->|"grounds in history"| node_hindsight
node_orchestrator -.->|"fallback"| node_local_memory
node_reasoning_engines -->|"enriches responses"| node_llm_service
node_llm_service -->|"builds prompts"| node_prompt_service
node_llm_service -->|"LLM inference"| node_groq
node_hindsight -->|"persistent recall"| node_hindsight_external
node_hindsight -.->|"unavailable fallback"| node_local_memory
node_memory_analytics -->|"recalled history"| node_hindsight
node_memory_analytics -->|"typed outputs"| node_memory_types
node_memory_views -->|"loads analytics"| node_api_client

click node_web_page "https://github.com/aspirant200715/cogni/blob/main/frontend/src/app/page.tsx"
click node_api_client "https://github.com/aspirant200715/cogni/blob/main/frontend/src/services/api.ts"
click node_memory_views "https://github.com/aspirant200715/cogni/blob/main/frontend/src/components/memory/MemoryTimeline.tsx"
click node_backend_entry "https://github.com/aspirant200715/cogni/blob/main/backend/run.py"
click node_fastapi_app "https://github.com/aspirant200715/cogni/blob/main/backend/app/main.py"
click node_study_routes "https://github.com/aspirant200715/cogni/blob/main/backend/app/routes/study_routes.py"
click node_socratic_routes "https://github.com/aspirant200715/cogni/blob/main/backend/app/routes/socratic_routes.py"
click node_insight_routes "https://github.com/aspirant200715/cogni/blob/main/backend/app/routes/insights_routes.py"
click node_memory_routes "https://github.com/aspirant200715/cogni/blob/main/backend/app/routes/memory_routes.py"
click node_orchestrator "https://github.com/aspirant200715/cogni/blob/main/backend/app/core/orchestrator.py"
click node_reasoning_engines "https://github.com/aspirant200715/cogni/blob/main/backend/app/engines/archaeology_engine.py"
click node_llm_service "https://github.com/aspirant200715/cogni/blob/main/backend/app/services/llm_service.py"
click node_prompt_service "https://github.com/aspirant200715/cogni/blob/main/backend/app/services/prompt_template_service.py"
click node_hindsight "https://github.com/aspirant200715/cogni/blob/main/backend/app/services/hindsight_service.py"
click node_local_memory "https://github.com/aspirant200715/cogni/blob/main/backend/app/services/local_memory_fallback.py"
click node_memory_analytics "https://github.com/aspirant200715/cogni/blob/main/backend/app/services/memory_analytics_service.py"
click node_summary_service "https://github.com/aspirant200715/cogni/blob/main/backend/app/services/summary_service.py"
click node_memory_types "https://github.com/aspirant200715/cogni/blob/main/backend/app/models/memory_types.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_page,node_api_client,node_memory_views toneBlue
class node_backend_entry,node_fastapi_app,node_study_routes,node_socratic_routes,node_insight_routes,node_memory_routes toneAmber
class node_orchestrator,node_reasoning_engines,node_llm_service,node_prompt_service toneMint
class node_hindsight,node_local_memory,node_memory_analytics,node_summary_service,node_memory_types toneRose
class node_groq,node_hindsight_external toneIndigo
```

## Components

### Next.js Client

- [Study UI](https://github.com/aspirant200715/cogni/blob/main/frontend/src/app/page.tsx): Next.js page · Selects study modes and presents coaching results. · `frontend/src/app/page.tsx`
- [API client](https://github.com/aspirant200715/cogni/blob/main/frontend/src/services/api.ts): TypeScript service · `frontend/src/services/api.ts`
- [Memory visualizations](https://github.com/aspirant200715/cogni/blob/main/frontend/src/components/memory/MemoryTimeline.tsx): React components · Timeline, confidence graph, and cognitive summary views. · `frontend/src/components/memory/MemoryTimeline.tsx`

### FastAPI API

- [Backend startup](https://github.com/aspirant200715/cogni/blob/main/backend/run.py): Python entry point · `backend/run.py`
- [FastAPI application](https://github.com/aspirant200715/cogni/blob/main/backend/app/main.py): API runtime · Serves public routes and API documentation. · `backend/app/main.py`
- [Study & quiz routes](https://github.com/aspirant200715/cogni/blob/main/backend/app/routes/study_routes.py): route module · `backend/app/routes/study_routes.py`
- [Socratic routes](https://github.com/aspirant200715/cogni/blob/main/backend/app/routes/socratic_routes.py): route module · `backend/app/routes/socratic_routes.py`
- [Insight routes](https://github.com/aspirant200715/cogni/blob/main/backend/app/routes/insights_routes.py): route module · `backend/app/routes/insights_routes.py`
- [Memory routes](https://github.com/aspirant200715/cogni/blob/main/backend/app/routes/memory_routes.py): route module · `backend/app/routes/memory_routes.py`

### Cognitive Reasoning

- [Hybrid orchestrator](https://github.com/aspirant200715/cogni/blob/main/backend/app/core/orchestrator.py): coordination service · Combines deterministic logic, recalled memory, LLM enrichment, and fallback. · `backend/app/core/orchestrator.py`
- [Specialized engines](https://github.com/aspirant200715/cogni/blob/main/backend/app/engines/archaeology_engine.py): reasoning engines · Archaeology, Socratic, Shadow, Resonance, Contagion, and Reflection engines. · `backend/app/engines/archaeology_engine.py`
- [LLM service](https://github.com/aspirant200715/cogni/blob/main/backend/app/services/llm_service.py): generation service · `backend/app/services/llm_service.py`
- [Prompt templates](https://github.com/aspirant200715/cogni/blob/main/backend/app/services/prompt_template_service.py): prompt service · `backend/app/services/prompt_template_service.py`

### Memory & Output

- [Hindsight integration](https://github.com/aspirant200715/cogni/blob/main/backend/app/services/hindsight_service.py): persistent memory service · `backend/app/services/hindsight_service.py`
- [Local memory fallback](https://github.com/aspirant200715/cogni/blob/main/backend/app/services/local_memory_fallback.py): resilient storage · Used when persistent memory is unavailable. · `backend/app/services/local_memory_fallback.py`
- [Memory analytics](https://github.com/aspirant200715/cogni/blob/main/backend/app/services/memory_analytics_service.py): analytics service · Builds timeline, confidence, and learner-profile outputs. · `backend/app/services/memory_analytics_service.py`
- [Summary & PDF output](https://github.com/aspirant200715/cogni/blob/main/backend/app/services/summary_service.py): output service · Produces study summaries and downloadable PDFs. · `backend/app/services/summary_service.py`
- [Memory domain types](https://github.com/aspirant200715/cogni/blob/main/backend/app/models/memory_types.py): payload models · `backend/app/models/memory_types.py`

### External Services

- **Groq**: hosted LLM · Requires GROQ_API_KEY.
- **Hindsight memory**: external memory

## Connections

- Study UI → API client: uses
- API client → FastAPI application: HTTP requests
- FastAPI application → Study & quiz routes: serves
- FastAPI application → Socratic routes: serves
- FastAPI application → Insight routes: serves
- FastAPI application → Memory routes: serves
- Backend startup → FastAPI application: starts
- Study & quiz routes → Hybrid orchestrator: logs and coaches
- Socratic routes → Hybrid orchestrator: multi-turn guidance
- Insight routes → Hybrid orchestrator: insights
- Memory routes → Memory analytics: retrieval analytics
- Memory routes → Summary & PDF output: summaries and export
- Hybrid orchestrator → Specialized engines: delegates reasoning
- Hybrid orchestrator → Hindsight integration: grounds in history
- Hybrid orchestrator → Local memory fallback: fallback
- Specialized engines → LLM service: enriches responses
- LLM service → Prompt templates: builds prompts
- LLM service → Groq: LLM inference
- Hindsight integration → Hindsight memory: persistent recall
- Hindsight integration → Local memory fallback: unavailable fallback
- Memory analytics → Hindsight integration: recalled history
- Memory analytics → Memory domain types: typed outputs
- Memory visualizations → API client: loads analytics