# sarahputhran/teachpivot architecture

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

- Interactive diagram: https://gitdiagram.com/sarahputhran/teachpivot
- Repository: https://github.com/sarahputhran/teachpivot

## Overview

TeachPivot supports teachers preparing for a classroom situation, consulting a context-specific Prep Card, and reflecting afterward; CRPs review collective signals and can revise guidance. The README documents these product stages and the bounded, pattern-based support model. Source evidence shows the frontend navigation and API boundary, backend route mounting, CRP signal orchestration, and reflection aggregation. Several route and page implementations were not excerpted, so some documented workflow links are shown with null evidence rather than inferred source calls.

Main entry points: [`backend/src/routes/crp.js`](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/crp.js) (CRP routes), [`frontend/src/api.js`](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/api.js) (API client), [`frontend/src/App.jsx`](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/App.jsx) (App navigation), [`backend/src/routes/index.js`](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/index.js) (API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_teacher["Teacher support"]
  node_app["App navigation<br/>[App.jsx]"]
  node_context["Context selection"]
  node_situation["Situation selection"]
  node_card_view["Prep Card view<br/>[PrepCardPage.jsx]"]
  node_reflection_view["Prep history and reflection"]
  node_reflection_form["Reflection form<br/>[ReflectionForm.jsx]"]
end

subgraph group_crp["CRP learning"]
  node_crp_dashboard["CRP dashboard<br/>[CRPDashboard.jsx]"]
end

subgraph group_backend["Backend services"]
  node_api["API client<br/>[api.js]"]
  node_normalize["Response normalization<br/>[normalize.ts]"]
  node_route_index["API router<br/>[index.js]"]
  node_curriculum_routes["Curriculum routes<br/>[curriculum.js]"]
  node_prep_routes["Prep Card routes<br/>[prepCard.js]"]
  node_reflection_routes["Reflection routes<br/>[reflection.js]"]
  node_crp_routes["CRP routes<br/>[crp.js]"]
  node_revision_routes["Revision routes<br/>[revisions.js]"]
  node_auth["Role authorization<br/>[roleAuth.js]"]
  node_summarizer["Review summarizer"]
end

subgraph group_data["Domain data"]
  node_prep_card[("Prep Card records<br/>[PrepCard.js]")]
  node_curriculum[("Curriculum records<br/>[Curriculum.js]")]
  node_reflection[("Reflection records<br/>[Reflection.js]")]
  node_aggregator["Reflection aggregation"]
  node_signals[("Aggregated signals")]
  node_themes["Theme extraction"]
  node_risk["Risk flagging<br/>[applyRiskFlags.js]"]
  node_crp_review[("CRP reviews<br/>[CRPReview.js]")]
  node_revisions[("Prep Card revisions")]
end

node_teacher(("Teacher"))
node_crp_actor(("CRP"))

node_teacher -.->|"starts"| node_app
node_app -->|"routes to"| node_context
node_app -->|"routes to"| node_situation
node_app -->|"routes to"| node_card_view
node_app -->|"routes to"| node_reflection_view
node_app -->|"routes to"| node_crp_dashboard
node_context -->|"requests topics"| node_api
node_situation -->|"requests situations"| node_api
node_card_view -->|"requests card"| node_api
node_reflection_view -->|"renders"| node_reflection_form
node_reflection_form -->|"submits reflection"| node_api
node_crp_dashboard -->|"requests dashboard"| node_api
node_api -.->|"calls REST API"| node_route_index
node_route_index -->|"mounts"| node_curriculum_routes
node_route_index -->|"mounts"| node_prep_routes
node_route_index -->|"mounts"| node_reflection_routes
node_route_index -->|"mounts"| node_crp_routes
node_route_index -->|"mounts"| node_revision_routes
node_curriculum_routes -->|"queries"| node_curriculum
node_prep_routes -->|"queries"| node_prep_card
node_prep_routes -->|"queries"| node_curriculum
node_crp_routes -->|"runs aggregation"| node_aggregator
node_crp_routes -->|"runs extraction"| node_themes
node_crp_routes -->|"runs flagging"| node_risk
node_aggregator -->|"reads"| node_reflection
node_aggregator -->|"writes"| node_signals
node_themes -->|"reads"| node_reflection
node_themes -->|"updates"| node_signals
node_risk -->|"updates flags"| node_signals
node_crp_routes -->|"queries"| node_signals
node_crp_routes -->|"records review"| node_crp_review
node_crp_routes -->|"queries cards"| node_prep_card
node_revision_routes -->|"manages"| node_revisions
node_revision_routes -->|"queries cards"| node_prep_card
node_crp_routes -->|"checks role"| node_auth
node_revision_routes -->|"checks role"| node_auth
node_crp_actor -.->|"reviews signals"| node_crp_dashboard
node_crp_routes -.->|"summarizes reviews"| node_summarizer
node_api -.->|"normalizes responses"| node_normalize

click node_app "https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/App.jsx"
click node_context "https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/pages/ContextSelection.jsx"
click node_situation "https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/pages/SituationSelection.jsx"
click node_card_view "https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/pages/PrepCardPage.jsx"
click node_reflection_view "https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/pages/PrepHistoryPage.jsx"
click node_reflection_form "https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/components/ReflectionForm.jsx"
click node_crp_dashboard "https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/pages/CRPDashboard.jsx"
click node_api "https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/api.js"
click node_normalize "https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/lib/normalize.ts"
click node_route_index "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/index.js"
click node_curriculum_routes "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/curriculum.js"
click node_prep_routes "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/prepCard.js"
click node_reflection_routes "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/reflection.js"
click node_crp_routes "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/crp.js"
click node_revision_routes "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/revisions.js"
click node_auth "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/middleware/roleAuth.js"
click node_summarizer "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/services/ReviewSummarizer.js"
click node_prep_card "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/PrepCard.js"
click node_curriculum "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/Curriculum.js"
click node_reflection "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/Reflection.js"
click node_aggregator "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/data/aggregateReflections.js"
click node_signals "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/AggregatedSignal.js"
click node_themes "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/data/extractThemeSignals.js"
click node_risk "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/data/applyRiskFlags.js"
click node_crp_review "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/CRPReview.js"
click node_revisions "https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/PrepCardRevision.js"

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_app,node_context,node_situation,node_card_view,node_reflection_view,node_reflection_form toneBlue
class node_crp_dashboard toneAmber
class node_api,node_normalize,node_route_index,node_curriculum_routes,node_prep_routes,node_reflection_routes,node_crp_routes,node_revision_routes,node_auth,node_summarizer toneMint
class node_prep_card,node_curriculum,node_reflection,node_aggregator,node_signals,node_themes,node_risk,node_crp_review,node_revisions toneRose
class node_teacher,node_crp_actor toneIndigo
```

## Components

### Teacher support

- [App navigation](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Context selection](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/pages/ContextSelection.jsx): `frontend/src/pages/ContextSelection.jsx`
- [Situation selection](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/pages/SituationSelection.jsx): `frontend/src/pages/SituationSelection.jsx`
- [Prep Card view](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/pages/PrepCardPage.jsx): `frontend/src/pages/PrepCardPage.jsx`
- [Prep history and reflection](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/pages/PrepHistoryPage.jsx): `frontend/src/pages/PrepHistoryPage.jsx`
- [Reflection form](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/components/ReflectionForm.jsx): `frontend/src/components/ReflectionForm.jsx`

### CRP learning

- [CRP dashboard](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/pages/CRPDashboard.jsx): `frontend/src/pages/CRPDashboard.jsx`

### Backend services

- [API client](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Response normalization](https://github.com/sarahputhran/teachpivot/blob/main/frontend/src/lib/normalize.ts): `frontend/src/lib/normalize.ts`
- [API router](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/index.js): `backend/src/routes/index.js`
- [Curriculum routes](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/curriculum.js): `backend/src/routes/curriculum.js`
- [Prep Card routes](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/prepCard.js): `backend/src/routes/prepCard.js`
- [Reflection routes](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/reflection.js): `backend/src/routes/reflection.js`
- [CRP routes](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/crp.js): `backend/src/routes/crp.js`
- [Revision routes](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/routes/revisions.js): `backend/src/routes/revisions.js`
- [Role authorization](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/middleware/roleAuth.js): `backend/src/middleware/roleAuth.js`
- [Review summarizer](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/services/ReviewSummarizer.js): `backend/src/services/ReviewSummarizer.js`

### Domain data

- [Prep Card records](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/PrepCard.js): `backend/src/models/PrepCard.js`
- [Curriculum records](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/Curriculum.js): `backend/src/models/Curriculum.js`
- [Reflection records](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/Reflection.js): `backend/src/models/Reflection.js`
- [Reflection aggregation](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/data/aggregateReflections.js): `backend/src/data/aggregateReflections.js`
- [Aggregated signals](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/AggregatedSignal.js): `backend/src/models/AggregatedSignal.js`
- [Theme extraction](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/data/extractThemeSignals.js): `backend/src/data/extractThemeSignals.js`
- [Risk flagging](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/data/applyRiskFlags.js): `backend/src/data/applyRiskFlags.js`
- [CRP reviews](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/CRPReview.js): `backend/src/models/CRPReview.js`
- [Prep Card revisions](https://github.com/sarahputhran/teachpivot/blob/main/backend/src/models/PrepCardRevision.js): `backend/src/models/PrepCardRevision.js`

### Other components

- **Teacher**
- **CRP**

## Connections

- Teacher → App navigation: starts (evidence: `README.md`)
- App navigation → Context selection: routes to (evidence: `frontend/src/App.jsx`)
- App navigation → Situation selection: routes to (evidence: `frontend/src/App.jsx`)
- App navigation → Prep Card view: routes to (evidence: `frontend/src/App.jsx`)
- App navigation → Prep history and reflection: routes to (evidence: `frontend/src/App.jsx`)
- App navigation → CRP dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Context selection → API client: requests topics (evidence: `frontend/src/pages/ContextSelection.jsx`)
- Situation selection → API client: requests situations (evidence: `frontend/src/api.js`)
- Prep Card view → API client: requests card (evidence: `frontend/src/api.js`)
- Prep history and reflection → Reflection form: renders (evidence: `frontend/src/pages/PrepHistoryPage.jsx`)
- Reflection form → API client: submits reflection (evidence: `frontend/src/components/ReflectionForm.jsx`)
- CRP dashboard → API client: requests dashboard (evidence: `frontend/src/pages/CRPDashboard.jsx`)
- API client → API router: calls REST API (evidence: `README.md`)
- API router → Curriculum routes: mounts (evidence: `backend/src/routes/index.js`)
- API router → Prep Card routes: mounts (evidence: `backend/src/routes/index.js`)
- API router → Reflection routes: mounts (evidence: `backend/src/routes/index.js`)
- API router → CRP routes: mounts (evidence: `backend/src/routes/index.js`)
- API router → Revision routes: mounts (evidence: `backend/src/routes/index.js`)
- Curriculum routes → Curriculum records: queries (evidence: `backend/src/routes/curriculum.js`)
- Prep Card routes → Prep Card records: queries (evidence: `backend/src/routes/prepCard.js`)
- Prep Card routes → Curriculum records: queries (evidence: `backend/src/routes/prepCard.js`)
- CRP routes → Reflection aggregation: runs aggregation (evidence: `backend/src/routes/crp.js`)
- CRP routes → Theme extraction: runs extraction (evidence: `backend/src/routes/crp.js`)
- CRP routes → Risk flagging: runs flagging (evidence: `backend/src/routes/crp.js`)
- Reflection aggregation → Reflection records: reads (evidence: `backend/src/data/aggregateReflections.js`)
- Reflection aggregation → Aggregated signals: writes (evidence: `backend/src/data/aggregateReflections.js`)
- Theme extraction → Reflection records: reads (evidence: `backend/src/data/extractThemeSignals.js`)
- Theme extraction → Aggregated signals: updates (evidence: `backend/src/data/extractThemeSignals.js`)
- Risk flagging → Aggregated signals: updates flags (evidence: `backend/src/data/applyRiskFlags.js`)
- CRP routes → Aggregated signals: queries (evidence: `backend/src/routes/crp.js`)
- CRP routes → CRP reviews: records review (evidence: `backend/src/routes/crp.js`)
- CRP routes → Prep Card records: queries cards (evidence: `backend/src/routes/crp.js`)
- Revision routes → Prep Card revisions: manages (evidence: `backend/src/routes/revisions.js`)
- Revision routes → Prep Card records: queries cards (evidence: `backend/src/routes/revisions.js`)
- CRP routes → Role authorization: checks role (evidence: `backend/src/routes/crp.js`)
- Revision routes → Role authorization: checks role (evidence: `backend/src/routes/revisions.js`)
- CRP → CRP dashboard: reviews signals (evidence: `README.md`)
- CRP routes → Review summarizer: summarizes reviews (evidence: `backend/src/routes/crp.js`)
- API client → Response normalization: normalizes responses
