BrainMap

BrainMap is a diagnostic-first learning app that builds a live concept map from real student performance.

Instead of suggesting what to study by fixed curriculum order, it recommends what to repair next based on:

• weak mastery
• concept bottleneck impact (prerequisite graph)
• recent mistakes

Current vertical: AP Physics 1.

Features

• 5-screen MVP flow:
  • onboarding
  • diagnostic / drill / daily question flow
  • brain map + next 3 nodes
  • concept node page with micro-lesson
  • session results with mastery deltas
• Evidence-based mastery updates (confidence-aware)
• Prerequisite graph and bottleneck recommender
• Mistake bank with review scheduling
• AI helpers (OpenAI):
  • contextual hint
  • wrong-answer explanation
  • isomorphic similar-question generation

Tech Stack

• Backend: TypeScript + Express + Postgres
• Frontend: Vanilla JS/CSS SPA served by Express
• AI: OpenAI API (chat.completions JSON mode)

System Architecture

flowchart LR
  U["Student"] --> FE["Vanilla SPA (app.js)"]
  FE --> API["Express API (index.ts)"]
  API --> D["Domain Logic (mastery/recommender/session selection/AI)"]
  D --> DB["Postgres (schema.sql)"]
  D --> OAI["OpenAI API (optional features)"]
  DB --> API
  API --> FE

Loading

Project Structure

• src/ backend API + domain logic
• public/ frontend SPA
• db/schema.sql schema
• db/seed.ts and db/seed-data.ts seed pipeline and starter data
• docs/ API contracts and demo workflows
• compose.yaml local Postgres helper

Prerequisites

• Node.js 20+
• npm 10+
• Docker Desktop (recommended) or local Postgres
• OpenAI API key (optional unless you want AI endpoints/features)

Setup

1. Clone and enter project.

git clone https://github.com/MaruthiV/brainmap.git
cd brainmap

2. Install dependencies.

npm install

3. Create env file.

cp .env.example .env

4. Edit .env.

PORT=3000
DATABASE_URL=postgres://postgres:postgres@localhost:5432/brainmap
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini

5. Start Postgres.

Option A (recommended):

npm run db:up

Option B: use your own Postgres and keep DATABASE_URL aligned.

6. Seed database.

npm run seed

7. Run app.

npm run dev

Open the URL printed in logs. If 3000 is busy, BrainMap auto-falls back to the next free port.

How To Use

1. Enter email, choose track, set goal date, click Continue.
2. Complete the 15-question diagnostic (required before map access).
3. Review your brain map and the next 3 nodes.
4. Start drills from weak nodes.
5. Run daily repair sessions to keep weak areas improving.
6. Use AI controls in question flow when needed:
   • AI Hint
   • AI: Why I Missed This
   • AI: Similar Question

Scripts

• npm run dev start dev server
• npm run build compile TypeScript
• npm run typecheck type checking only
• npm run seed create/update schema and seed data
• npm run db:up start Postgres via Docker
• npm run db:down stop Postgres and remove volume

API

• See docs/api.md for endpoint contracts.
• See docs/demo-workflow.md for cURL workflow.

Current Content

• 1 track: ap-physics-1
• 20 concepts + prerequisite edges
• 20 concept micro-lessons
• 40 starter MCQs with concept tags

License

No license file is currently included. Add one before public/commercial distribution.