# nicolaspozzi/notiontutor architecture

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

- Interactive diagram: https://gitdiagram.com/nicolaspozzi/notiontutor
- Repository: https://github.com/nicolaspozzi/notiontutor

## Overview

NotionTutor turns a user’s Notion pages into interactive AI revision sessions, tracks answers for spaced repetition, and can deliver scheduled email digests. The principal flow is page discovery, revision-session creation, answering, and history/stats; digest management and daily delivery are a separate capability. Routes orchestrate adapters and persistence, with session verification, encryption, and validation as shared internal services. The graph reflects the excerpts and SOURCE INDEX references; dashboard-to-route wiring and several route implementations were not inspected, so those links are not asserted.

Main entry points: [`src/app/api/revisions/route.ts`](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/revisions/route.ts) (Start revision), [`src/lib/db/prisma.ts`](https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/db/prisma.ts) (Postgres data), [`src/app/api/cron/send-digests/route.ts`](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/cron/send-digests/route.ts) (Digest delivery job), [`src/lib/auth/session.ts`](https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/auth/session.ts) (Session security)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_page_browser["Notion pages<br/>[page.tsx]"]
  node_history_ui["Revision history<br/>[page.tsx]"]
  node_digest_ui["Digest settings<br/>[page.tsx]"]
end

subgraph group_revision["Revision workflow"]
  node_page_routes["Page routes<br/>[route.ts]"]
  node_revision_start["Start revision<br/>[route.ts]"]
  node_answer_route["Submit answer<br/>[route.ts]"]
  node_history_routes["History routes<br/>[route.ts]"]
  node_stats_route["Progress stats<br/>[route.ts]"]
end

subgraph group_digests["Email digests"]
  node_digest_routes["Digest management<br/>[route.ts]"]
  node_digest_job["Digest delivery job<br/>[route.ts]"]
end

subgraph group_services["Shared services"]
  node_notion_adapter["Notion adapter<br/>[client.ts]"]
  node_llm_adapter["Question generator<br/>[openai-adapter.ts]"]
  node_auth_session["Session security<br/>[session.ts]"]
  node_encryption["Encrypted fields<br/>[encryption.ts]"]
  node_validation["Request validation<br/>[validation.ts]"]
  node_database[("Postgres data<br/>[prisma.ts]")]
end

node_user(("Learner"))
node_resend["Resend email"]
node_openai["OpenAI"]

node_user -->|"uses"| node_dashboard
node_user -->|"selects pages"| node_page_browser
node_user -->|"configures digests"| node_digest_ui
node_page_routes -->|"verifies session"| node_auth_session
node_page_routes -->|"reads token"| node_database
node_page_routes -->|"decrypts token"| node_encryption
node_page_routes -->|"searches pages"| node_notion_adapter
node_revision_start -->|"verifies session"| node_auth_session
node_revision_start -->|"validates input"| node_validation
node_revision_start -->|"reads and writes"| node_database
node_revision_start -->|"decrypts token"| node_encryption
node_revision_start -->|"encrypts questions"| node_encryption
node_revision_start -->|"fetches page"| node_notion_adapter
node_revision_start -->|"generates questions"| node_llm_adapter
node_notion_adapter -->|"calls Notion API"| node_openai
node_llm_adapter -->|"generates with"| node_openai
node_answer_route -->|"verifies session"| node_auth_session
node_answer_route -->|"validates input"| node_validation
node_answer_route -->|"updates answers"| node_database
node_history_routes -->|"verifies session"| node_auth_session
node_history_routes -->|"reads history"| node_database
node_stats_route -->|"verifies session"| node_auth_session
node_stats_route -->|"reads progress"| node_database
node_digest_routes -->|"verifies session"| node_auth_session
node_digest_routes -->|"validates input"| node_validation
node_digest_routes -->|"reads and writes"| node_database
node_digest_job -->|"loads and updates"| node_database
node_digest_job -->|"fetches page"| node_notion_adapter
node_digest_job -->|"generates question"| node_llm_adapter
node_digest_job -->|"decrypts token"| node_encryption
node_digest_job -->|"sends email"| node_resend

click node_dashboard "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/dashboard/page.tsx"
click node_page_browser "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/dashboard/pages/page.tsx"
click node_history_ui "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/dashboard/history/page.tsx"
click node_digest_ui "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/dashboard/digests/page.tsx"
click node_page_routes "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/pages/route.ts"
click node_revision_start "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/revisions/route.ts"
click node_answer_route "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/revisions/%5BsessionId%5D/answer/route.ts"
click node_history_routes "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/history/route.ts"
click node_stats_route "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/stats/route.ts"
click node_notion_adapter "https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/adapters/notion/client.ts"
click node_llm_adapter "https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/adapters/llm/openai-adapter.ts"
click node_digest_routes "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/digests/route.ts"
click node_digest_job "https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/cron/send-digests/route.ts"
click node_auth_session "https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/auth/session.ts"
click node_encryption "https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/auth/encryption.ts"
click node_validation "https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/validation.ts"
click node_database "https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/db/prisma.ts"

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_dashboard,node_page_browser,node_history_ui,node_digest_ui toneBlue
class node_page_routes,node_revision_start,node_answer_route,node_history_routes,node_stats_route toneAmber
class node_digest_routes,node_digest_job toneMint
class node_notion_adapter,node_llm_adapter,node_auth_session,node_encryption,node_validation,node_database toneRose
class node_user,node_resend,node_openai toneIndigo
```

## Components

### User experience

- [Dashboard](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Notion pages](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/dashboard/pages/page.tsx): `src/app/dashboard/pages/page.tsx`
- [Revision history](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/dashboard/history/page.tsx): `src/app/dashboard/history/page.tsx`
- [Digest settings](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/dashboard/digests/page.tsx): `src/app/dashboard/digests/page.tsx`

### Revision workflow

- [Page routes](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/pages/route.ts): `src/app/api/pages/route.ts`
- [Start revision](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/revisions/route.ts): `src/app/api/revisions/route.ts`
- [Submit answer](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/revisions/%5BsessionId%5D/answer/route.ts): `src/app/api/revisions/[sessionId]/answer/route.ts`
- [History routes](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/history/route.ts): `src/app/api/history/route.ts`
- [Progress stats](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/stats/route.ts): `src/app/api/stats/route.ts`

### Email digests

- [Digest management](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/digests/route.ts): `src/app/api/digests/route.ts`
- [Digest delivery job](https://github.com/nicolaspozzi/notiontutor/blob/main/src/app/api/cron/send-digests/route.ts): `src/app/api/cron/send-digests/route.ts`

### Shared services

- [Notion adapter](https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/adapters/notion/client.ts): `src/lib/adapters/notion/client.ts`
- [Question generator](https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/adapters/llm/openai-adapter.ts): `src/lib/adapters/llm/openai-adapter.ts`
- [Session security](https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/auth/session.ts): `src/lib/auth/session.ts`
- [Encrypted fields](https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/auth/encryption.ts): `src/lib/auth/encryption.ts`
- [Request validation](https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/validation.ts): `src/lib/validation.ts`
- [Postgres data](https://github.com/nicolaspozzi/notiontutor/blob/main/src/lib/db/prisma.ts): `src/lib/db/prisma.ts`

### Other components

- **Learner**
- **Resend email**
- **OpenAI**

## Connections

- Learner → Dashboard: uses (evidence: `README.md`)
- Learner → Notion pages: selects pages (evidence: `README.md`)
- Learner → Digest settings: configures digests (evidence: `README.md`)
- Page routes → Session security: verifies session (evidence: `src/app/api/pages/route.ts`)
- Page routes → Postgres data: reads token (evidence: `src/app/api/pages/route.ts`)
- Page routes → Encrypted fields: decrypts token (evidence: `src/app/api/pages/route.ts`)
- Page routes → Notion adapter: searches pages (evidence: `src/app/api/pages/route.ts`)
- Start revision → Session security: verifies session (evidence: `src/app/api/revisions/route.ts`)
- Start revision → Request validation: validates input (evidence: `src/app/api/revisions/route.ts`)
- Start revision → Postgres data: reads and writes (evidence: `src/app/api/revisions/route.ts`)
- Start revision → Encrypted fields: decrypts token (evidence: `src/app/api/revisions/route.ts`)
- Start revision → Encrypted fields: encrypts questions (evidence: `src/app/api/revisions/route.ts`)
- Start revision → Notion adapter: fetches page (evidence: `src/app/api/revisions/route.ts`)
- Start revision → Question generator: generates questions (evidence: `src/app/api/revisions/route.ts`)
- Notion adapter → OpenAI: calls Notion API (evidence: `src/lib/adapters/notion/client.ts`)
- Question generator → OpenAI: generates with (evidence: `README.md`)
- Submit answer → Session security: verifies session (evidence: `src/app/api/revisions/[sessionId]/answer/route.ts`)
- Submit answer → Request validation: validates input (evidence: `src/app/api/revisions/[sessionId]/answer/route.ts`)
- Submit answer → Postgres data: updates answers (evidence: `src/app/api/revisions/[sessionId]/answer/route.ts`)
- History routes → Session security: verifies session (evidence: `src/app/api/history/route.ts`)
- History routes → Postgres data: reads history (evidence: `src/app/api/history/route.ts`)
- Progress stats → Session security: verifies session (evidence: `src/app/api/stats/route.ts`)
- Progress stats → Postgres data: reads progress (evidence: `src/app/api/stats/route.ts`)
- Digest management → Session security: verifies session (evidence: `src/app/api/digests/route.ts`)
- Digest management → Request validation: validates input (evidence: `src/app/api/digests/route.ts`)
- Digest management → Postgres data: reads and writes (evidence: `src/app/api/digests/route.ts`)
- Digest delivery job → Postgres data: loads and updates (evidence: `src/app/api/cron/send-digests/route.ts`)
- Digest delivery job → Notion adapter: fetches page (evidence: `src/app/api/cron/send-digests/route.ts`)
- Digest delivery job → Question generator: generates question (evidence: `src/app/api/cron/send-digests/route.ts`)
- Digest delivery job → Encrypted fields: decrypts token (evidence: `src/app/api/cron/send-digests/route.ts`)
- Digest delivery job → Resend email: sends email (evidence: `src/app/api/cron/send-digests/route.ts`)
