aspirant200715/cogni

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.