# zaintahir2025/neuroscript-ai architecture

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

- Interactive diagram: https://gitdiagram.com/zaintahir2025/neuroscript-ai
- Repository: https://github.com/zaintahir2025/neuroscript-ai

## Overview

NeuroScript AI is an offline-first accessible study app: students capture notes, review OCR text, generate structured lessons, then study flashcards or explore concept maps. README documents the client pipeline and privacy boundary; sampled server code confirms proxy validation, rate limiting, provider dispatch, and Gemini calls. Flutter implementation details were not sampled, so client-stage edges rely on README statements; planned roadmap capabilities are omitted.

Main entry points: [`server/NeuroScriptProxy/Program.cs`](https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Program.cs) (Proxy endpoints), [`lib/features/lesson/lesson_overview_screen.dart`](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/lesson/lesson_overview_screen.dart) (Lesson overview), [`lib/features/capture/capture_screen.dart`](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/capture/capture_screen.dart) (Capture screen), [`lib/services/image_preprocessor.dart`](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/services/image_preprocessor.dart) (Image processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Note capture"]
  node_capture_ui["Capture screen"]
  node_preprocess["Image processing"]
  node_ocr["On-device OCR<br/>[ocr_service.dart]"]
  node_ocr_review["Transcript review"]
end

subgraph group_learning["Study experience"]
  node_library["Lesson library"]
  node_lesson["Lesson overview"]
  node_review["Flashcard review"]
  node_concept_map["Concept map"]
  node_accessibility["Accessibility settings"]
end

subgraph group_clientcore["Client services"]
  node_proxy_client["Proxy client<br/>[proxy_service.dart]"]
  node_local_db[("Encrypted SQLite<br/>[database.dart]")]
  node_scheduler["Leitner scheduler"]
end

subgraph group_backend["AI proxy"]
  node_proxy_entry["Proxy endpoints<br/>[Program.cs]"]
  node_contracts["Lesson contracts<br/>[LessonContracts.cs]"]
  node_limiter["Rate limiter<br/>[RateLimiter.cs]"]
  node_generator_contract["Generator interface"]
  node_gemini_generator["Gemini generator"]
  node_mock_generator["Mock generator"]
end

node_student(("Student"))
node_gemini_api["Google Gemini"]

node_student -->|"captures notes"| node_capture_ui
node_capture_ui -->|"preprocesses images"| node_preprocess
node_preprocess -->|"recognizes text"| node_ocr
node_ocr -->|"reviews transcript"| node_ocr_review
node_ocr_review -->|"requests synthesis"| node_proxy_client
node_proxy_client -->|"sends lesson request"| node_proxy_entry
node_proxy_entry -->|"accepts request"| node_contracts
node_proxy_entry -->|"checks quota"| node_limiter
node_proxy_entry -->|"dispatches generation"| node_generator_contract
node_proxy_entry -->|"registers provider"| node_gemini_generator
node_proxy_entry -->|"registers fallback"| node_mock_generator
node_gemini_generator -->|"calls API"| node_gemini_api
node_proxy_entry -.->|"returns lesson for storage"| node_local_db
node_local_db -.->|"provides saved lessons"| node_library
node_library -.->|"opens lesson"| node_lesson
node_lesson -->|"offers flashcards"| node_review
node_review -->|"schedules recall"| node_scheduler
node_lesson -->|"shows concept map"| node_concept_map
node_student -->|"chooses profile"| node_accessibility

click node_capture_ui "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/capture/capture_screen.dart"
click node_preprocess "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/services/image_preprocessor.dart"
click node_ocr "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/services/ocr_service.dart"
click node_ocr_review "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/ocr_review/ocr_review_screen.dart"
click node_proxy_client "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/services/proxy_service.dart"
click node_proxy_entry "https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Program.cs"
click node_contracts "https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Models/LessonContracts.cs"
click node_limiter "https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Services/RateLimiter.cs"
click node_generator_contract "https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Services/ILessonGenerator.cs"
click node_gemini_generator "https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Services/GeminiLessonGenerator.cs"
click node_mock_generator "https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Services/MockLessonGenerator.cs"
click node_local_db "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/data/database/database.dart"
click node_library "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/library/library_screen.dart"
click node_lesson "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/lesson/lesson_overview_screen.dart"
click node_review "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/review/flashcard_review_screen.dart"
click node_scheduler "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/services/leitner_scheduler.dart"
click node_concept_map "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/concept_map/concept_map_screen.dart"
click node_accessibility "https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/settings/settings_screen.dart"

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_capture_ui,node_preprocess,node_ocr,node_ocr_review toneBlue
class node_library,node_lesson,node_review,node_concept_map,node_accessibility toneAmber
class node_proxy_client,node_local_db,node_scheduler toneMint
class node_proxy_entry,node_contracts,node_limiter,node_generator_contract,node_gemini_generator,node_mock_generator toneRose
class node_student,node_gemini_api toneIndigo
```

## Components

### Note capture

- [Capture screen](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/capture/capture_screen.dart): `lib/features/capture/capture_screen.dart`
- [Image processing](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/services/image_preprocessor.dart): `lib/services/image_preprocessor.dart`
- [On-device OCR](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/services/ocr_service.dart): `lib/services/ocr_service.dart`
- [Transcript review](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/ocr_review/ocr_review_screen.dart): `lib/features/ocr_review/ocr_review_screen.dart`

### Study experience

- [Lesson library](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/library/library_screen.dart): `lib/features/library/library_screen.dart`
- [Lesson overview](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/lesson/lesson_overview_screen.dart): `lib/features/lesson/lesson_overview_screen.dart`
- [Flashcard review](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/review/flashcard_review_screen.dart): `lib/features/review/flashcard_review_screen.dart`
- [Concept map](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/concept_map/concept_map_screen.dart): `lib/features/concept_map/concept_map_screen.dart`
- [Accessibility settings](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/features/settings/settings_screen.dart): `lib/features/settings/settings_screen.dart`

### Client services

- [Proxy client](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/services/proxy_service.dart): `lib/services/proxy_service.dart`
- [Encrypted SQLite](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/data/database/database.dart): `lib/data/database/database.dart`
- [Leitner scheduler](https://github.com/zaintahir2025/neuroscript-ai/blob/main/lib/services/leitner_scheduler.dart): `lib/services/leitner_scheduler.dart`

### AI proxy

- [Proxy endpoints](https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Program.cs): `server/NeuroScriptProxy/Program.cs`
- [Lesson contracts](https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Models/LessonContracts.cs): `server/NeuroScriptProxy/Models/LessonContracts.cs`
- [Rate limiter](https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Services/RateLimiter.cs): `server/NeuroScriptProxy/Services/RateLimiter.cs`
- [Generator interface](https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Services/ILessonGenerator.cs): `server/NeuroScriptProxy/Services/ILessonGenerator.cs`
- [Gemini generator](https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Services/GeminiLessonGenerator.cs): `server/NeuroScriptProxy/Services/GeminiLessonGenerator.cs`
- [Mock generator](https://github.com/zaintahir2025/neuroscript-ai/blob/main/server/NeuroScriptProxy/Services/MockLessonGenerator.cs): `server/NeuroScriptProxy/Services/MockLessonGenerator.cs`

### Other components

- **Student**
- **Google Gemini**

## Connections

- Student → Capture screen: captures notes (evidence: `README.md`)
- Capture screen → Image processing: preprocesses images (evidence: `README.md`)
- Image processing → On-device OCR: recognizes text (evidence: `README.md`)
- On-device OCR → Transcript review: reviews transcript (evidence: `README.md`)
- Transcript review → Proxy client: requests synthesis (evidence: `README.md`)
- Proxy client → Proxy endpoints: sends lesson request (evidence: `README.md`)
- Proxy endpoints → Lesson contracts: accepts request (evidence: `server/NeuroScriptProxy/Program.cs`)
- Proxy endpoints → Rate limiter: checks quota (evidence: `server/NeuroScriptProxy/Program.cs`)
- Proxy endpoints → Generator interface: dispatches generation (evidence: `server/NeuroScriptProxy/Program.cs`)
- Proxy endpoints → Gemini generator: registers provider (evidence: `server/NeuroScriptProxy/Program.cs`)
- Proxy endpoints → Mock generator: registers fallback (evidence: `server/NeuroScriptProxy/Program.cs`)
- Gemini generator → Google Gemini: calls API (evidence: `server/NeuroScriptProxy/Services/GeminiLessonGenerator.cs`)
- Proxy endpoints → Encrypted SQLite: returns lesson for storage
- Encrypted SQLite → Lesson library: provides saved lessons
- Lesson library → Lesson overview: opens lesson
- Lesson overview → Flashcard review: offers flashcards (evidence: `README.md`)
- Flashcard review → Leitner scheduler: schedules recall (evidence: `README.md`)
- Lesson overview → Concept map: shows concept map (evidence: `README.md`)
- Student → Accessibility settings: chooses profile (evidence: `README.md`)
