# cammelo/sbp architecture

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

- Interactive diagram: https://gitdiagram.com/cammelo/sbp
- Repository: https://github.com/cammelo/sbp

## Overview

SBP serves a Git-backed blog: visitors request the README homepage or Markdown posts, which are rendered through repository data into Jinja templates; a protected sync endpoint handles repository updates. A push workflow can initiate sync, which pulls Git changes, reconciles post metadata and the file tree, then commits and pushes the SQLite database. Initialization clones the target repository and prepares the database. Source excerpts show the principal routes and sync implementation; template/static serving and several setup details are documented but their target-repository files are not part of this repository.

Main entry points: [`src/sbp/repository.py`](https://github.com/cammelo/sbp/blob/master/src/sbp/repository.py) (Blog repository), [`src/sbp/main.py`](https://github.com/cammelo/sbp/blob/master/src/sbp/main.py) (HTTP routes), [`src/sbp/init.py`](https://github.com/cammelo/sbp/blob/master/src/sbp/init.py) (Repository initializer), [`src/sbp/database.py`](https://github.com/cammelo/sbp/blob/master/src/sbp/database.py) (SQLite session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Blog serving"]
  node_routes["HTTP routes<br/>[main.py]"]
  node_repository["Blog repository<br/>[repository.py]"]
  node_markdown["Markdown renderer<br/>[markdown.py]"]
  node_templates["Blog templates"]
  node_static_assets["Static assets"]
end

subgraph group_sync["Repository sync"]
  node_sync_workflow["Sync handler<br/>[main.py]"]
  node_reconcile["Post reconciliation<br/>[repository.py]"]
  node_head_tree["Head and tree state<br/>[repository.py]"]
end

subgraph group_state["Configuration and state"]
  node_config["Settings<br/>[config.py]"]
  node_database[("SQLite session<br/>[database.py]")]
  node_models["Post and head records<br/>[models.py]"]
  node_logger["Sync logging<br/>[logs.py]"]
end

subgraph group_startup["Application startup"]
  node_app["FastAPI app<br/>[__init__.py]"]
  node_init["Repository initializer<br/>[init.py]"]
end

node_visitor(("Blog visitor"))
node_push_workflow(("Push workflow"))
node_git_remote["Git remote"]

node_visitor -->|"requests pages"| node_routes
node_routes -->|"loads posts"| node_repository
node_repository -->|"converts Markdown"| node_markdown
node_routes -.->|"renders page"| node_templates
node_routes -.->|"serves assets"| node_static_assets
node_routes -->|"checks token"| node_config
node_push_workflow -->|"calls sync endpoint"| node_sync_workflow
node_sync_workflow -->|"schedules sync"| node_repository
node_repository -->|"pulls and pushes"| node_git_remote
node_repository -->|"reconciles changes"| node_reconcile
node_repository -->|"updates state"| node_head_tree
node_reconcile -->|"uses sessions"| node_database
node_head_tree -->|"reads and updates"| node_models
node_reconcile -->|"stores post metadata"| node_models
node_database -->|"gets database path"| node_config
node_repository -->|"logs sync"| node_logger
node_init -->|"clones and syncs"| node_repository
node_init -->|"creates schema"| node_database
node_init -->|"reads repository settings"| node_config
node_app -->|"registers routes"| node_routes

click node_app "https://github.com/cammelo/sbp/blob/master/src/sbp/__init__.py"
click node_routes "https://github.com/cammelo/sbp/blob/master/src/sbp/main.py"
click node_repository "https://github.com/cammelo/sbp/blob/master/src/sbp/repository.py"
click node_markdown "https://github.com/cammelo/sbp/blob/master/src/sbp/markdown.py"
click node_init "https://github.com/cammelo/sbp/blob/master/src/sbp/init.py"
click node_config "https://github.com/cammelo/sbp/blob/master/src/sbp/config.py"
click node_database "https://github.com/cammelo/sbp/blob/master/src/sbp/database.py"
click node_models "https://github.com/cammelo/sbp/blob/master/src/sbp/models.py"
click node_sync_workflow "https://github.com/cammelo/sbp/blob/master/src/sbp/main.py"
click node_reconcile "https://github.com/cammelo/sbp/blob/master/src/sbp/repository.py"
click node_head_tree "https://github.com/cammelo/sbp/blob/master/src/sbp/repository.py"
click node_logger "https://github.com/cammelo/sbp/blob/master/src/sbp/logs.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_routes,node_repository,node_markdown,node_templates,node_static_assets toneBlue
class node_sync_workflow,node_reconcile,node_head_tree toneAmber
class node_config,node_database,node_models,node_logger toneMint
class node_app,node_init toneRose
class node_visitor,node_push_workflow,node_git_remote toneIndigo
```

## Components

### Blog serving

- [HTTP routes](https://github.com/cammelo/sbp/blob/master/src/sbp/main.py): `src/sbp/main.py`
- [Blog repository](https://github.com/cammelo/sbp/blob/master/src/sbp/repository.py): `src/sbp/repository.py`
- [Markdown renderer](https://github.com/cammelo/sbp/blob/master/src/sbp/markdown.py): `src/sbp/markdown.py`
- **Blog templates**
- **Static assets**

### Repository sync

- [Sync handler](https://github.com/cammelo/sbp/blob/master/src/sbp/main.py): `src/sbp/main.py`
- [Post reconciliation](https://github.com/cammelo/sbp/blob/master/src/sbp/repository.py): `src/sbp/repository.py`
- [Head and tree state](https://github.com/cammelo/sbp/blob/master/src/sbp/repository.py): `src/sbp/repository.py`

### Configuration and state

- [Settings](https://github.com/cammelo/sbp/blob/master/src/sbp/config.py): `src/sbp/config.py`
- [SQLite session](https://github.com/cammelo/sbp/blob/master/src/sbp/database.py): `src/sbp/database.py`
- [Post and head records](https://github.com/cammelo/sbp/blob/master/src/sbp/models.py): `src/sbp/models.py`
- [Sync logging](https://github.com/cammelo/sbp/blob/master/src/sbp/logs.py): `src/sbp/logs.py`

### Application startup

- [FastAPI app](https://github.com/cammelo/sbp/blob/master/src/sbp/__init__.py): `src/sbp/__init__.py`
- [Repository initializer](https://github.com/cammelo/sbp/blob/master/src/sbp/init.py): `src/sbp/init.py`

### Other components

- **Blog visitor**
- **Push workflow**
- **Git remote**

## Connections

- Blog visitor → HTTP routes: requests pages (evidence: `src/sbp/main.py`)
- HTTP routes → Blog repository: loads posts (evidence: `src/sbp/main.py`)
- Blog repository → Markdown renderer: converts Markdown (evidence: `src/sbp/repository.py`)
- HTTP routes → Blog templates: renders page (evidence: `README.md`)
- HTTP routes → Static assets: serves assets (evidence: `src/sbp/main.py`)
- HTTP routes → Settings: checks token (evidence: `src/sbp/main.py`)
- Push workflow → Sync handler: calls sync endpoint (evidence: `README.md`)
- Sync handler → Blog repository: schedules sync (evidence: `src/sbp/main.py`)
- Blog repository → Git remote: pulls and pushes (evidence: `src/sbp/repository.py`)
- Blog repository → Post reconciliation: reconciles changes (evidence: `src/sbp/repository.py`)
- Blog repository → Head and tree state: updates state (evidence: `src/sbp/repository.py`)
- Post reconciliation → SQLite session: uses sessions (evidence: `src/sbp/repository.py`)
- Head and tree state → Post and head records: reads and updates (evidence: `src/sbp/repository.py`)
- Post reconciliation → Post and head records: stores post metadata (evidence: `src/sbp/repository.py`)
- SQLite session → Settings: gets database path (evidence: `src/sbp/database.py`)
- Blog repository → Sync logging: logs sync (evidence: `src/sbp/repository.py`)
- Repository initializer → Blog repository: clones and syncs (evidence: `src/sbp/init.py`)
- Repository initializer → SQLite session: creates schema (evidence: `src/sbp/init.py`)
- Repository initializer → Settings: reads repository settings (evidence: `src/sbp/init.py`)
- FastAPI app → HTTP routes: registers routes (evidence: `src/sbp/__init__.py`)
