# lc-1220/pathfinder architecture

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

- Interactive diagram: https://gitdiagram.com/lc-1220/pathfinder
- Repository: https://github.com/lc-1220/pathfinder

## Overview

PathFinder is a student-profile and academic-program guidance web app. Students sign in or use a guest session, submit report cards, review extracted academic details, and receive course recommendations; the app also provides course chat and administrative/student-management pages. The main runtime is concentrated in fasthtml_app.py, with browser behavior in static/StudentApp.js and OCR modules in ocr/. The README documents Supabase Postgres and Docling use. Source excerpts do not show all route handlers or database operations, so uncertain internal links are omitted or marked unverified.

Main entry points: [`fasthtml_app.py`](https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py) (Web app and routes), [`static/StudentApp.js`](https://github.com/lc-1220/pathfinder/blob/main/static/StudentApp.js) (Student workspace), [`static/Login.js`](https://github.com/lc-1220/pathfinder/blob/main/static/Login.js) (Login UI), [`ocr/docling_service.py`](https://github.com/lc-1220/pathfinder/blob/main/ocr/docling_service.py) (Docling conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_browser["Browser pages"]
  node_login["Login UI<br/>[Login.js]"]
  node_student_ui["Student workspace<br/>[StudentApp.js]"]
end

subgraph group_app["Application"]
  node_app_runtime["Web app and routes<br/>[fasthtml_app.py]"]
  node_auth["Authentication<br/>[fasthtml_app.py]"]
  node_profiles["Student profiles<br/>[fasthtml_app.py]"]
  node_recommendations["Course recommendations<br/>[fasthtml_app.py]"]
  node_course_chat["Course chat<br/>[fasthtml_app.py]"]
end

subgraph group_ocr["Report-card OCR"]
  node_docling["Docling conversion<br/>[docling_service.py]"]
  node_ocr_parser["Report-card parsing<br/>[parser.py]"]
  node_preprocessing["Image preprocessing<br/>[preprocessing.py]"]
  node_table_extraction["Table extraction"]
end

subgraph group_data["Persistence"]
  node_postgres[("Supabase Postgres")]
end

node_student(("Student"))
node_admin(("Administrator"))
node_supabase["Supabase service"]

node_student -->|"signs in"| node_login
node_login -->|"submits credentials"| node_auth
node_student -->|"uses workspace"| node_student_ui
node_admin -.->|"uses admin pages"| node_browser
node_student_ui -->|"sends chat request"| node_course_chat
node_app_runtime -.->|"handles sign-in"| node_auth
node_app_runtime -.->|"serves profile routes"| node_profiles
node_app_runtime -->|"computes guidance"| node_recommendations
node_app_runtime -->|"handles chat"| node_course_chat
node_app_runtime -->|"uses OCR provider"| node_docling
node_app_runtime -->|"imports parser"| node_ocr_parser
node_student_ui -.->|"uploads report cards"| node_docling
node_app_runtime -->|"uses configured database"| node_postgres
node_supabase -->|"hosts database"| node_postgres

click node_browser "https://github.com/lc-1220/pathfinder/tree/main/templates"
click node_login "https://github.com/lc-1220/pathfinder/blob/main/static/Login.js"
click node_student_ui "https://github.com/lc-1220/pathfinder/blob/main/static/StudentApp.js"
click node_app_runtime "https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py"
click node_auth "https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py"
click node_profiles "https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py"
click node_recommendations "https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py"
click node_course_chat "https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py"
click node_docling "https://github.com/lc-1220/pathfinder/blob/main/ocr/docling_service.py"
click node_ocr_parser "https://github.com/lc-1220/pathfinder/blob/main/ocr/parser.py"
click node_preprocessing "https://github.com/lc-1220/pathfinder/blob/main/ocr/preprocessing.py"
click node_table_extraction "https://github.com/lc-1220/pathfinder/blob/main/ocr/table_extraction.py"
click node_postgres "https://github.com/lc-1220/pathfinder/blob/main/supabase_schema.sql"

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_browser,node_login,node_student_ui toneBlue
class node_app_runtime,node_auth,node_profiles,node_recommendations,node_course_chat toneAmber
class node_docling,node_ocr_parser,node_preprocessing,node_table_extraction toneMint
class node_postgres toneRose
class node_student,node_admin,node_supabase toneIndigo
```

## Components

### Web experience

- [Browser pages](https://github.com/lc-1220/pathfinder/tree/main/templates): `templates`
- [Login UI](https://github.com/lc-1220/pathfinder/blob/main/static/Login.js): `static/Login.js`
- [Student workspace](https://github.com/lc-1220/pathfinder/blob/main/static/StudentApp.js): `static/StudentApp.js`

### Application

- [Web app and routes](https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py): `fasthtml_app.py`
- [Authentication](https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py): `fasthtml_app.py`
- [Student profiles](https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py): `fasthtml_app.py`
- [Course recommendations](https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py): `fasthtml_app.py`
- [Course chat](https://github.com/lc-1220/pathfinder/blob/main/fasthtml_app.py): `fasthtml_app.py`

### Report-card OCR

- [Docling conversion](https://github.com/lc-1220/pathfinder/blob/main/ocr/docling_service.py): `ocr/docling_service.py`
- [Report-card parsing](https://github.com/lc-1220/pathfinder/blob/main/ocr/parser.py): `ocr/parser.py`
- [Image preprocessing](https://github.com/lc-1220/pathfinder/blob/main/ocr/preprocessing.py): `ocr/preprocessing.py`
- [Table extraction](https://github.com/lc-1220/pathfinder/blob/main/ocr/table_extraction.py): `ocr/table_extraction.py`

### Persistence

- [Supabase Postgres](https://github.com/lc-1220/pathfinder/blob/main/supabase_schema.sql): `supabase_schema.sql`

### Other components

- **Student**
- **Administrator**
- **Supabase service**

## Connections

- Student → Login UI: signs in (evidence: `static/Login.js`)
- Login UI → Authentication: submits credentials (evidence: `static/Login.js`)
- Student → Student workspace: uses workspace (evidence: `static/StudentApp.js`)
- Administrator → Browser pages: uses admin pages
- Student workspace → Course chat: sends chat request (evidence: `static/StudentApp.js`)
- Web app and routes → Authentication: handles sign-in (evidence: `fasthtml_app.py`)
- Web app and routes → Student profiles: serves profile routes (evidence: `fasthtml_app.py`)
- Web app and routes → Course recommendations: computes guidance (evidence: `fasthtml_app.py`)
- Web app and routes → Course chat: handles chat (evidence: `fasthtml_app.py`)
- Web app and routes → Docling conversion: uses OCR provider (evidence: `README.md`)
- Web app and routes → Report-card parsing: imports parser (evidence: `fasthtml_app.py`)
- Student workspace → Docling conversion: uploads report cards
- Web app and routes → Supabase Postgres: uses configured database (evidence: `README.md`)
- Supabase service → Supabase Postgres: hosts database (evidence: `README.md`)