# selfxplanatorium/delphee architecture

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

- Interactive diagram: https://gitdiagram.com/selfxplanatorium/delphee
- Repository: https://github.com/selfxplanatorium/delphee

## Overview

Delphee is an HTTP wrapper and browser interface for the Delphi student portal. A user signs in, receives a bearer token, and requests student data; the service authenticates to Delphi, parses its HTML into JSON, and may serve cached results. Major branches include academic records and plans, exams and sessions, fees and receipts, certificates, and student services. The README also documents an offline demo. Source excerpts establish the login, routing, session, and cache behavior; endpoint coverage is grouped by domain where implementation details were not excerpted.

Main entry points: [`src/server/api.ts`](https://github.com/selfxplanatorium/delphee/blob/main/src/server/api.ts) (Data API), [`src/server/routes.ts`](https://github.com/selfxplanatorium/delphee/blob/main/src/server/routes.ts) (HTTP routes), [`src/server/sessions.ts`](https://github.com/selfxplanatorium/delphee/blob/main/src/server/sessions.ts) (Session registry), [`src/server/session-middleware.ts`](https://github.com/selfxplanatorium/delphee/blob/main/src/server/session-middleware.ts) (Session middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP and interface"]
  node_browser["Browser UI<br/>[app.js]"]
  node_routes["HTTP routes<br/>[routes.ts]"]
  node_shell["Page shell<br/>[index.html.ts]"]
end

subgraph group_auth["Sessions and access"]
  node_middleware["Session middleware"]
  node_registry["Session registry<br/>[sessions.ts]"]
  node_session["Delphi session<br/>[session.ts]"]
  node_demo["Demo API<br/>[demo.ts]"]
end

subgraph group_data["Portal data"]
  node_api["Data API<br/>[api.ts]"]
  node_profile["Profile and career<br/>[anagrafica.ts]"]
  node_academic["Study plans<br/>[piano.ts]"]
  node_exams["Exams and sessions<br/>[esami-search.ts]"]
  node_finance["Fees and payments<br/>[bollettini.ts]"]
  node_services["Services and codes<br/>[servizi.ts]"]
  node_certificates["Certificates<br/>[certificati.ts]"]
end

subgraph group_runtime["Shared runtime"]
  node_fetcher["HTTP fetcher<br/>[fetcher.ts]"]
  node_cookiejar["Cookie jar<br/>[cookie-jar.ts]"]
  node_cache[("Memory cache<br/>[store.ts]")]
  node_retry["Retry policy<br/>[retry.ts]"]
  node_config["Runtime config<br/>[config.ts]"]
end

node_user(("Student"))
node_delphi["Delphi portal"]

node_user -->|"uses"| node_browser
node_browser -->|"requests"| node_routes
node_routes -->|"renders"| node_shell
node_routes -->|"authenticates via"| node_middleware
node_routes -->|"logs in through"| node_registry
node_middleware -->|"looks up session"| node_registry
node_middleware -->|"selects live API"| node_api
node_middleware -->|"selects demo API"| node_demo
node_registry -->|"creates and manages"| node_session
node_registry -->|"creates demo session"| node_demo
node_session -->|"authenticates via"| node_fetcher
node_fetcher -->|"maintains cookies"| node_cookiejar
node_fetcher -->|"retries transient errors"| node_retry
node_api -->|"fetches authenticated pages"| node_session
node_api -->|"reads and writes"| node_cache
node_api -->|"parses profile data"| node_profile
node_api -->|"parses study plans"| node_academic
node_api -->|"parses exam data"| node_exams
node_api -->|"parses payment data"| node_finance
node_api -->|"parses services"| node_services
node_api -->|"parses certificates"| node_certificates
node_fetcher -->|"requests portal pages"| node_delphi
node_api -->|"proxies portal pages"| node_delphi
node_registry -.->|"evicts account data"| node_cache
node_routes -.->|"uses configuration"| node_config

click node_browser "https://github.com/selfxplanatorium/delphee/blob/main/src/server/static/app.js"
click node_routes "https://github.com/selfxplanatorium/delphee/blob/main/src/server/routes.ts"
click node_shell "https://github.com/selfxplanatorium/delphee/blob/main/src/server/static/index.html.ts"
click node_middleware "https://github.com/selfxplanatorium/delphee/blob/main/src/server/session-middleware.ts"
click node_registry "https://github.com/selfxplanatorium/delphee/blob/main/src/server/sessions.ts"
click node_session "https://github.com/selfxplanatorium/delphee/blob/main/src/client/session.ts"
click node_demo "https://github.com/selfxplanatorium/delphee/blob/main/src/server/demo.ts"
click node_api "https://github.com/selfxplanatorium/delphee/blob/main/src/server/api.ts"
click node_profile "https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/anagrafica.ts"
click node_academic "https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/piano.ts"
click node_exams "https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/esami-search.ts"
click node_finance "https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/bollettini.ts"
click node_services "https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/servizi.ts"
click node_certificates "https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/certificati.ts"
click node_fetcher "https://github.com/selfxplanatorium/delphee/blob/main/src/client/fetcher.ts"
click node_cookiejar "https://github.com/selfxplanatorium/delphee/blob/main/src/client/cookie-jar.ts"
click node_cache "https://github.com/selfxplanatorium/delphee/blob/main/src/cache/store.ts"
click node_retry "https://github.com/selfxplanatorium/delphee/blob/main/src/utils/retry.ts"
click node_config "https://github.com/selfxplanatorium/delphee/blob/main/src/config.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_browser,node_routes,node_shell toneBlue
class node_middleware,node_registry,node_session,node_demo toneAmber
class node_api,node_profile,node_academic,node_exams,node_finance,node_services,node_certificates toneMint
class node_fetcher,node_cookiejar,node_cache,node_retry,node_config toneRose
class node_user,node_delphi toneIndigo
```

## Components

### HTTP and interface

- [Browser UI](https://github.com/selfxplanatorium/delphee/blob/main/src/server/static/app.js): `src/server/static/app.js`
- [HTTP routes](https://github.com/selfxplanatorium/delphee/blob/main/src/server/routes.ts): `src/server/routes.ts`
- [Page shell](https://github.com/selfxplanatorium/delphee/blob/main/src/server/static/index.html.ts): `src/server/static/index.html.ts`

### Sessions and access

- [Session middleware](https://github.com/selfxplanatorium/delphee/blob/main/src/server/session-middleware.ts): `src/server/session-middleware.ts`
- [Session registry](https://github.com/selfxplanatorium/delphee/blob/main/src/server/sessions.ts): `src/server/sessions.ts`
- [Delphi session](https://github.com/selfxplanatorium/delphee/blob/main/src/client/session.ts): `src/client/session.ts`
- [Demo API](https://github.com/selfxplanatorium/delphee/blob/main/src/server/demo.ts): `src/server/demo.ts`

### Portal data

- [Data API](https://github.com/selfxplanatorium/delphee/blob/main/src/server/api.ts): `src/server/api.ts`
- [Profile and career](https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/anagrafica.ts): `src/client/endpoints/anagrafica.ts`
- [Study plans](https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/piano.ts): `src/client/endpoints/piano.ts`
- [Exams and sessions](https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/esami-search.ts): `src/client/endpoints/esami-search.ts`
- [Fees and payments](https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/bollettini.ts): `src/client/endpoints/bollettini.ts`
- [Services and codes](https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/servizi.ts): `src/client/endpoints/servizi.ts`
- [Certificates](https://github.com/selfxplanatorium/delphee/blob/main/src/client/endpoints/certificati.ts): `src/client/endpoints/certificati.ts`

### Shared runtime

- [HTTP fetcher](https://github.com/selfxplanatorium/delphee/blob/main/src/client/fetcher.ts): `src/client/fetcher.ts`
- [Cookie jar](https://github.com/selfxplanatorium/delphee/blob/main/src/client/cookie-jar.ts): `src/client/cookie-jar.ts`
- [Memory cache](https://github.com/selfxplanatorium/delphee/blob/main/src/cache/store.ts): `src/cache/store.ts`
- [Retry policy](https://github.com/selfxplanatorium/delphee/blob/main/src/utils/retry.ts): `src/utils/retry.ts`
- [Runtime config](https://github.com/selfxplanatorium/delphee/blob/main/src/config.ts): `src/config.ts`

### Other components

- **Student**
- **Delphi portal**

## Connections

- Student → Browser UI: uses (evidence: `README.md`)
- Browser UI → HTTP routes: requests (evidence: `README.md`)
- HTTP routes → Page shell: renders (evidence: `src/server/routes.ts`)
- HTTP routes → Session middleware: authenticates via (evidence: `src/server/routes.ts`)
- HTTP routes → Session registry: logs in through (evidence: `src/server/routes.ts`)
- Session middleware → Session registry: looks up session (evidence: `src/server/session-middleware.ts`)
- Session middleware → Data API: selects live API (evidence: `src/server/session-middleware.ts`)
- Session middleware → Demo API: selects demo API (evidence: `src/server/session-middleware.ts`)
- Session registry → Delphi session: creates and manages (evidence: `src/server/sessions.ts`)
- Session registry → Demo API: creates demo session (evidence: `src/server/sessions.ts`)
- Delphi session → HTTP fetcher: authenticates via (evidence: `src/client/session.ts`)
- HTTP fetcher → Cookie jar: maintains cookies (evidence: `src/client/fetcher.ts`)
- HTTP fetcher → Retry policy: retries transient errors (evidence: `src/client/fetcher.ts`)
- Data API → Delphi session: fetches authenticated pages (evidence: `src/server/api.ts`)
- Data API → Memory cache: reads and writes (evidence: `src/server/api.ts`)
- Data API → Profile and career: parses profile data (evidence: `src/server/api.ts`)
- Data API → Study plans: parses study plans (evidence: `src/server/api.ts`)
- Data API → Exams and sessions: parses exam data (evidence: `src/server/api.ts`)
- Data API → Fees and payments: parses payment data (evidence: `src/server/api.ts`)
- Data API → Services and codes: parses services (evidence: `src/server/api.ts`)
- Data API → Certificates: parses certificates (evidence: `src/server/api.ts`)
- HTTP fetcher → Delphi portal: requests portal pages (evidence: `README.md`)
- Data API → Delphi portal: proxies portal pages (evidence: `README.md`)
- Session registry → Memory cache: evicts account data
- HTTP routes → Runtime config: uses configuration (evidence: `src/server/routes.ts`)
