# nathanblatter/personal-site architecture

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

- Interactive diagram: https://gitdiagram.com/nathanblatter/personal-site
- Repository: https://github.com/nathanblatter/personal-site

## Overview

This is a personal portfolio and services site with a React frontend, FastAPI API, and PostgreSQL-backed content. The principal visitor workflow is route selection, page rendering, and API-backed content display; the admin side edits portfolio and consulting data. The repository also includes a journal processing subsystem and file storage. Several backend capabilities are visible in the tree and source index but not sampled, so their internal relationships are omitted unless documented or indexed.

Main entry points: [`backend/app/database.py`](https://github.com/nathanblatter/personal-site/blob/main/backend/app/database.py) (Database sessions), [`backend/app/main.py`](https://github.com/nathanblatter/personal-site/blob/main/backend/app/main.py) (HTTP application), [`backend/app/routers/crm.py`](https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/crm.py) (Consulting CRM), [`backend/app/routers/journal.py`](https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/journal.py) (Journal API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Portfolio frontend"]
  node_app["Route application<br/>[App.tsx]"]
  node_pages["Portfolio pages"]
  node_adminui["Admin workspace<br/>[Admin.tsx]"]
  node_apiclient["API client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_fastapi["HTTP application<br/>[main.py]"]
  node_auth["Admin authentication<br/>[auth.py]"]
end

subgraph group_content["Content and consulting"]
  node_portfolio["Portfolio content routes<br/>[about.py]"]
  node_servicecontent["Services content<br/>[services.py]"]
  node_crm["Consulting CRM<br/>[crm.py]"]
  node_schemas["API data schemas<br/>[schemas.py]"]
end

subgraph group_journal["Journal system"]
  node_journalroutes["Journal API<br/>[journal.py]"]
  node_journalworker["Journal worker<br/>[journal_worker.py]"]
  node_vocab["Vocabulary pipeline<br/>[vocab_service.py]"]
  node_vocabseed["Vocabulary seed<br/>[journal_vocab.py]"]
end

subgraph group_infra["Shared services"]
  node_storage["Object storage API<br/>[storage.py]"]
  node_database["Database sessions<br/>[database.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_cache["Response cache<br/>[cache.py]"]
end

node_visitor(("Site visitor"))
node_admin(("Site administrator"))
node_postgres[("PostgreSQL")]
node_objectstore[("S3-compatible storage")]

node_visitor -->|"opens site"| node_app
node_admin -->|"manages content"| node_adminui
node_app -->|"routes to"| node_pages
node_pages -->|"requests content"| node_apiclient
node_adminui -->|"submits changes"| node_apiclient
node_apiclient -->|"calls API"| node_fastapi
node_fastapi -->|"registers routes"| node_portfolio
node_fastapi -->|"registers routes"| node_servicecontent
node_fastapi -->|"registers routes"| node_crm
node_portfolio -.->|"queries data"| node_database
node_servicecontent -->|"queries and updates"| node_database
node_servicecontent -->|"invalidates cache"| node_cache
node_crm -->|"uses sessions"| node_database
node_crm -->|"uses models"| node_models
node_crm -->|"uses schemas"| node_schemas
node_database -->|"connects"| node_postgres
node_models -->|"uses base"| node_database
node_journalroutes -->|"uses vocabulary"| node_vocab
node_journalroutes -->|"uses storage"| node_storage
node_journalworker -->|"extracts candidates"| node_vocab
node_journalworker -->|"references API"| node_journalroutes
node_vocab -->|"uses seed terms"| node_vocabseed
node_storage -->|"stores and lists files"| node_objectstore
node_journalroutes -->|"checks access"| node_auth
node_storage -->|"checks access"| node_auth

click node_app "https://github.com/nathanblatter/personal-site/blob/main/frontend/src/App.tsx"
click node_pages "https://github.com/nathanblatter/personal-site/tree/main/frontend/src/pages"
click node_adminui "https://github.com/nathanblatter/personal-site/blob/main/frontend/src/pages/Admin.tsx"
click node_apiclient "https://github.com/nathanblatter/personal-site/blob/main/frontend/src/lib/api.ts"
click node_fastapi "https://github.com/nathanblatter/personal-site/blob/main/backend/app/main.py"
click node_auth "https://github.com/nathanblatter/personal-site/blob/main/backend/app/auth.py"
click node_portfolio "https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/about.py"
click node_servicecontent "https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/services.py"
click node_crm "https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/crm.py"
click node_schemas "https://github.com/nathanblatter/personal-site/blob/main/backend/app/schemas.py"
click node_journalroutes "https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/journal.py"
click node_journalworker "https://github.com/nathanblatter/personal-site/blob/main/backend/app/journal_worker.py"
click node_vocab "https://github.com/nathanblatter/personal-site/blob/main/backend/app/vocab_service.py"
click node_vocabseed "https://github.com/nathanblatter/personal-site/blob/main/backend/app/journal_vocab.py"
click node_storage "https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/storage.py"
click node_database "https://github.com/nathanblatter/personal-site/blob/main/backend/app/database.py"
click node_models "https://github.com/nathanblatter/personal-site/blob/main/backend/app/models.py"
click node_cache "https://github.com/nathanblatter/personal-site/blob/main/backend/app/cache.py"

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_pages,node_adminui,node_apiclient toneBlue
class node_fastapi,node_auth,node_postgres,node_objectstore toneAmber
class node_portfolio,node_servicecontent,node_crm,node_schemas toneMint
class node_journalroutes,node_journalworker,node_vocab,node_vocabseed toneRose
class node_storage,node_database,node_models,node_cache,node_visitor,node_admin toneIndigo
```

## Components

### Portfolio frontend

- [Route application](https://github.com/nathanblatter/personal-site/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Portfolio pages](https://github.com/nathanblatter/personal-site/tree/main/frontend/src/pages): `frontend/src/pages`
- [Admin workspace](https://github.com/nathanblatter/personal-site/blob/main/frontend/src/pages/Admin.tsx): `frontend/src/pages/Admin.tsx`
- [API client](https://github.com/nathanblatter/personal-site/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Backend API

- [HTTP application](https://github.com/nathanblatter/personal-site/blob/main/backend/app/main.py): `backend/app/main.py`
- [Admin authentication](https://github.com/nathanblatter/personal-site/blob/main/backend/app/auth.py): `backend/app/auth.py`

### Content and consulting

- [Portfolio content routes](https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/about.py): `backend/app/routers/about.py`
- [Services content](https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/services.py): `backend/app/routers/services.py`
- [Consulting CRM](https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/crm.py): `backend/app/routers/crm.py`
- [API data schemas](https://github.com/nathanblatter/personal-site/blob/main/backend/app/schemas.py): `backend/app/schemas.py`

### Journal system

- [Journal API](https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/journal.py): `backend/app/routers/journal.py`
- [Journal worker](https://github.com/nathanblatter/personal-site/blob/main/backend/app/journal_worker.py): `backend/app/journal_worker.py`
- [Vocabulary pipeline](https://github.com/nathanblatter/personal-site/blob/main/backend/app/vocab_service.py): `backend/app/vocab_service.py`
- [Vocabulary seed](https://github.com/nathanblatter/personal-site/blob/main/backend/app/journal_vocab.py): `backend/app/journal_vocab.py`

### Shared services

- [Object storage API](https://github.com/nathanblatter/personal-site/blob/main/backend/app/routers/storage.py): `backend/app/routers/storage.py`
- [Database sessions](https://github.com/nathanblatter/personal-site/blob/main/backend/app/database.py): `backend/app/database.py`
- [Domain models](https://github.com/nathanblatter/personal-site/blob/main/backend/app/models.py): `backend/app/models.py`
- [Response cache](https://github.com/nathanblatter/personal-site/blob/main/backend/app/cache.py): `backend/app/cache.py`

### Other components

- **Site visitor**
- **Site administrator**
- **PostgreSQL**
- **S3-compatible storage**

## Connections

- Site visitor → Route application: opens site (evidence: `frontend/src/App.tsx`)
- Site administrator → Admin workspace: manages content
- Route application → Portfolio pages: routes to (evidence: `frontend/src/App.tsx`)
- Portfolio pages → API client: requests content (evidence: `frontend/src/lib/api.ts`)
- Admin workspace → API client: submits changes
- API client → HTTP application: calls API (evidence: `README.md`)
- HTTP application → Portfolio content routes: registers routes (evidence: `backend/app/main.py`)
- HTTP application → Services content: registers routes (evidence: `backend/app/main.py`)
- HTTP application → Consulting CRM: registers routes (evidence: `backend/app/main.py`)
- Portfolio content routes → Database sessions: queries data
- Services content → Database sessions: queries and updates (evidence: `backend/app/routers/services.py`)
- Services content → Response cache: invalidates cache (evidence: `backend/app/routers/services.py`)
- Consulting CRM → Database sessions: uses sessions (evidence: `backend/app/routers/crm.py`)
- Consulting CRM → Domain models: uses models (evidence: `backend/app/routers/crm.py`)
- Consulting CRM → API data schemas: uses schemas (evidence: `backend/app/routers/crm.py`)
- Database sessions → PostgreSQL: connects (evidence: `README.md`)
- Domain models → Database sessions: uses base (evidence: `backend/app/models.py`)
- Journal API → Vocabulary pipeline: uses vocabulary (evidence: `backend/app/routers/journal.py`)
- Journal API → Object storage API: uses storage (evidence: `backend/app/routers/journal.py`)
- Journal worker → Vocabulary pipeline: extracts candidates (evidence: `backend/app/journal_worker.py`)
- Journal worker → Journal API: references API (evidence: `backend/app/journal_worker.py`)
- Vocabulary pipeline → Vocabulary seed: uses seed terms (evidence: `backend/app/vocab_service.py`)
- Object storage API → S3-compatible storage: stores and lists files (evidence: `backend/app/routers/storage.py`)
- Journal API → Admin authentication: checks access (evidence: `backend/app/routers/journal.py`)
- Object storage API → Admin authentication: checks access (evidence: `backend/app/routers/storage.py`)
