# sayahosea/braille architecture

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

- Interactive diagram: https://gitdiagram.com/sayahosea/braille
- Repository: https://github.com/sayahosea/braille

## Overview

braille is a Deno-hosted online braille course with account management, authenticated sessions, course lessons, quizzes, and per-account progress. A visitor enters through the Hono app; its middleware enforces session access, and course routes render lessons while quiz submissions are checked and progress is recorded. The graph also shows the account API and persistence layer. Source excerpts establish the main wiring; individual account handlers and several page/client details were not sampled, so their internal dependencies are not inferred.

Main entry points: [`src/handlers/Database.js`](https://github.com/sayahosea/braille/blob/main/src/handlers/Database.js) (Database access), [`src/main.js`](https://github.com/sayahosea/braille/blob/main/src/main.js) (Hono app), [`src/routers/API.js`](https://github.com/sayahosea/braille/blob/main/src/routers/API.js) (Account and quiz API), [`src/routes/courses/index.js`](https://github.com/sayahosea/braille/blob/main/src/routes/courses/index.js) (Course index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Web application"]
  node_app["Hono app<br/>[main.js]"]
  node_route_handlers["Page handlers<br/>[Routes.js]"]
  node_api_router["Account and quiz API<br/>[API.js]"]
  node_util["Shared utilities<br/>[Util.js]"]
end

subgraph group_learning["Course learning"]
  node_course_router["Course router<br/>[Courses.js]"]
  node_course_index["Course index<br/>[index.js]"]
  node_course_start["Lesson renderer<br/>[start.js]"]
  node_course_data["Course content<br/>[Courses.js]"]
  node_quiz["Quiz validation<br/>[validate.js]"]
end

subgraph group_accounts["Accounts and sessions"]
  node_auth["Session middleware<br/>[AuthPlugin.js]"]
  node_account_api["Account operations"]
  node_cookie["Signed cookies<br/>[Cookie.js]"]
end

subgraph group_persistence["Persistence"]
  node_database["Database access<br/>[Database.js]"]
  node_accounts_store["Account records<br/>[Account.js]"]
  node_sessions_store["Session records<br/>[Session.js]"]
  node_progress_store["Course progress<br/>[Progress.js]"]
end

node_visitor(("Visitor"))
node_postgres[("PostgreSQL")]

node_visitor -->|"requests pages"| node_app
node_app -->|"initializes"| node_database
node_app -->|"applies middleware"| node_auth
node_app -->|"mounts API"| node_api_router
node_app -->|"mounts courses"| node_course_router
node_app -->|"dispatches pages"| node_route_handlers
node_api_router -->|"dispatches account routes"| node_account_api
node_api_router -->|"dispatches validation"| node_quiz
node_course_router -->|"dispatches course index"| node_course_index
node_course_index -->|"dispatches lesson"| node_course_start
node_course_index -->|"loads course metadata"| node_course_data
node_course_start -->|"reads progress"| node_database
node_course_start -->|"renders lesson"| node_util
node_quiz -->|"checks answers against"| node_course_data
node_quiz -->|"reads and updates progress"| node_database
node_auth -->|"reads session cookie"| node_cookie
node_auth -->|"checks session and account"| node_database
node_database -->|"exposes account operations"| node_accounts_store
node_database -->|"exposes session operations"| node_sessions_store
node_database -->|"exposes progress operations"| node_progress_store
node_database -->|"queries"| node_postgres

click node_app "https://github.com/sayahosea/braille/blob/main/src/main.js"
click node_auth "https://github.com/sayahosea/braille/blob/main/src/handlers/AuthPlugin.js"
click node_route_handlers "https://github.com/sayahosea/braille/blob/main/src/handlers/Routes.js"
click node_api_router "https://github.com/sayahosea/braille/blob/main/src/routers/API.js"
click node_course_router "https://github.com/sayahosea/braille/blob/main/src/routers/Courses.js"
click node_course_index "https://github.com/sayahosea/braille/blob/main/src/routes/courses/index.js"
click node_course_start "https://github.com/sayahosea/braille/blob/main/src/routes/courses/start.js"
click node_course_data "https://github.com/sayahosea/braille/blob/main/src/handlers/Courses.js"
click node_quiz "https://github.com/sayahosea/braille/blob/main/src/api/quiz/validate.js"
click node_account_api "https://github.com/sayahosea/braille/tree/main/src/api/account"
click node_cookie "https://github.com/sayahosea/braille/blob/main/src/handlers/Cookie.js"
click node_util "https://github.com/sayahosea/braille/blob/main/src/handlers/Util.js"
click node_database "https://github.com/sayahosea/braille/blob/main/src/handlers/Database.js"
click node_accounts_store "https://github.com/sayahosea/braille/blob/main/src/database/Account.js"
click node_sessions_store "https://github.com/sayahosea/braille/blob/main/src/database/Session.js"
click node_progress_store "https://github.com/sayahosea/braille/blob/main/src/database/Progress.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_route_handlers,node_api_router,node_util toneBlue
class node_course_router,node_course_index,node_course_start,node_course_data,node_quiz,node_postgres toneAmber
class node_auth,node_account_api,node_cookie toneMint
class node_database,node_accounts_store,node_sessions_store,node_progress_store toneRose
class node_visitor toneIndigo
```

## Components

### Web application

- [Hono app](https://github.com/sayahosea/braille/blob/main/src/main.js): `src/main.js`
- [Page handlers](https://github.com/sayahosea/braille/blob/main/src/handlers/Routes.js): `src/handlers/Routes.js`
- [Account and quiz API](https://github.com/sayahosea/braille/blob/main/src/routers/API.js): `src/routers/API.js`
- [Shared utilities](https://github.com/sayahosea/braille/blob/main/src/handlers/Util.js): `src/handlers/Util.js`

### Course learning

- [Course router](https://github.com/sayahosea/braille/blob/main/src/routers/Courses.js): `src/routers/Courses.js`
- [Course index](https://github.com/sayahosea/braille/blob/main/src/routes/courses/index.js): `src/routes/courses/index.js`
- [Lesson renderer](https://github.com/sayahosea/braille/blob/main/src/routes/courses/start.js): `src/routes/courses/start.js`
- [Course content](https://github.com/sayahosea/braille/blob/main/src/handlers/Courses.js): `src/handlers/Courses.js`
- [Quiz validation](https://github.com/sayahosea/braille/blob/main/src/api/quiz/validate.js): `src/api/quiz/validate.js`

### Accounts and sessions

- [Session middleware](https://github.com/sayahosea/braille/blob/main/src/handlers/AuthPlugin.js): `src/handlers/AuthPlugin.js`
- [Account operations](https://github.com/sayahosea/braille/tree/main/src/api/account): `src/api/account`
- [Signed cookies](https://github.com/sayahosea/braille/blob/main/src/handlers/Cookie.js): `src/handlers/Cookie.js`

### Persistence

- [Database access](https://github.com/sayahosea/braille/blob/main/src/handlers/Database.js): `src/handlers/Database.js`
- [Account records](https://github.com/sayahosea/braille/blob/main/src/database/Account.js): `src/database/Account.js`
- [Session records](https://github.com/sayahosea/braille/blob/main/src/database/Session.js): `src/database/Session.js`
- [Course progress](https://github.com/sayahosea/braille/blob/main/src/database/Progress.js): `src/database/Progress.js`

### Other components

- **Visitor**
- **PostgreSQL**

## Connections

- Visitor → Hono app: requests pages (evidence: `README.md`)
- Hono app → Database access: initializes (evidence: `src/main.js`)
- Hono app → Session middleware: applies middleware (evidence: `src/main.js`)
- Hono app → Account and quiz API: mounts API (evidence: `src/main.js`)
- Hono app → Course router: mounts courses (evidence: `src/main.js`)
- Hono app → Page handlers: dispatches pages (evidence: `src/main.js`)
- Account and quiz API → Account operations: dispatches account routes (evidence: `src/routers/API.js`)
- Account and quiz API → Quiz validation: dispatches validation (evidence: `src/routers/API.js`)
- Course router → Course index: dispatches course index (evidence: `src/routers/Courses.js`)
- Course index → Lesson renderer: dispatches lesson (evidence: `src/routes/courses/index.js`)
- Course index → Course content: loads course metadata (evidence: `src/routes/courses/index.js`)
- Lesson renderer → Database access: reads progress (evidence: `src/routes/courses/start.js`)
- Lesson renderer → Shared utilities: renders lesson (evidence: `src/routes/courses/start.js`)
- Quiz validation → Course content: checks answers against (evidence: `src/api/quiz/validate.js`)
- Quiz validation → Database access: reads and updates progress (evidence: `src/api/quiz/validate.js`)
- Session middleware → Signed cookies: reads session cookie (evidence: `src/handlers/AuthPlugin.js`)
- Session middleware → Database access: checks session and account (evidence: `src/handlers/AuthPlugin.js`)
- Database access → Account records: exposes account operations (evidence: `src/handlers/Database.js`)
- Database access → Session records: exposes session operations (evidence: `src/handlers/Database.js`)
- Database access → Course progress: exposes progress operations (evidence: `src/handlers/Database.js`)
- Database access → PostgreSQL: queries (evidence: `src/handlers/Database.js`)
