# josepvco/source-provisioner architecture

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

- Interactive diagram: https://gitdiagram.com/josepvco/source-provisioner
- Repository: https://github.com/josepvco/source-provisioner

## Overview

Source Provisioner turns a YAML desired-state file into platform sources: validate it, optionally discover accounts and generate named, templated, staggered sources, then resolve, diff, apply changes idempotently, and report results. The client talks to a fictional FastAPI platform that serves account discovery and source CRUD, backed by SQLite with token authentication and rate limiting; optional fault injection is also documented. The notebook is the user-facing orchestrator. Unsampled API modules and notebook internals are represented only where the README or source index supports their role and connections.

Main entry points: [`src/provisioner/sync.py`](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/sync.py) (Sync orchestration), [`api/mock_platform/main.py`](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/main.py) (API application), [`src/provisioner/generate.py`](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/generate.py) (Generation pipeline), [`api/mock_platform/routes/sources.py`](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/routes/sources.py) (Source CRUD routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provision["Provisioning client"]
  node_notebook["Notebook workflow"]
  node_schema["Schema validation<br/>[schema.py]"]
  node_sync["Sync orchestration<br/>[sync.py]"]
  node_resolve["Resolve extensions<br/>[extend.py]"]
  node_diff["Plan diff<br/>[diff.py]"]
  node_client["HTTP client<br/>[client.py]"]
  node_report["Run report<br/>[report.py]"]
  node_logs["Structured logging<br/>[logs.py]"]
end

subgraph group_generation["Source generation"]
  node_generation["Generation pipeline<br/>[generate.py]"]
  node_naming["Source naming<br/>[naming.py]"]
  node_template["Template rendering<br/>[template.py]"]
  node_stagger["Schedule staggering<br/>[stagger.py]"]
end

subgraph group_platform["Mock platform"]
  node_api_app["API application<br/>[main.py]"]
  node_accounts["Account routes<br/>[accounts.py]"]
  node_discovery["Seeded account data<br/>[discovery.py]"]
  node_sources["Source CRUD routes<br/>[sources.py]"]
  node_database[("SQLite storage<br/>[db.py]")]
  node_models["API data models<br/>[models.py]"]
end

subgraph group_platform_support["Platform controls"]
  node_auth["Bearer authentication<br/>[auth.py]"]
  node_ratelimit["Rate limiting<br/>[ratelimit.py]"]
  node_chaos["Fault injection<br/>[chaos.py]"]
end

node_operator(("Operator"))
node_yaml["Desired-state YAML"]

node_operator -->|"runs workflow"| node_notebook
node_yaml -->|"provides desired state"| node_notebook
node_notebook -->|"loads and validates"| node_schema
node_notebook -->|"invokes sync"| node_sync
node_sync -->|"resolves sources"| node_resolve
node_resolve -->|"runs discoverers"| node_generation
node_generation -->|"lists accounts"| node_client
node_generation -->|"renders payloads"| node_template
node_generation -->|"builds names"| node_naming
node_generation -->|"computes schedules"| node_stagger
node_sync -->|"plans changes"| node_diff
node_sync -->|"reads and applies"| node_client
node_sync -->|"records outcomes"| node_report
node_sync -->|"logs run"| node_logs
node_client -->|"calls platform API"| node_api_app
node_api_app -->|"mounts routes"| node_accounts
node_api_app -->|"mounts routes"| node_sources
node_api_app -->|"initializes database"| node_database
node_api_app -->|"configures limiter"| node_ratelimit
node_api_app -->|"optionally installs"| node_chaos
node_accounts -->|"lists accounts"| node_discovery
node_sources -->|"requires token"| node_auth
node_sources -->|"enforces limits"| node_ratelimit
node_sources -->|"reads and writes"| node_database
node_sources -->|"uses request models"| node_models
node_accounts -->|"requires token"| node_auth
node_accounts -->|"enforces limits"| node_ratelimit

click node_notebook "https://github.com/josepvco/source-provisioner/blob/main/notebooks/provision_sources.ipynb"
click node_schema "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/schema.py"
click node_sync "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/sync.py"
click node_resolve "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/extend.py"
click node_diff "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/diff.py"
click node_client "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/client.py"
click node_report "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/report.py"
click node_logs "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/logs.py"
click node_generation "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/generate.py"
click node_naming "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/naming.py"
click node_template "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/template.py"
click node_stagger "https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/stagger.py"
click node_api_app "https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/main.py"
click node_accounts "https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/routes/accounts.py"
click node_discovery "https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/discovery.py"
click node_sources "https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/routes/sources.py"
click node_database "https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/db.py"
click node_models "https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/models.py"
click node_auth "https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/auth.py"
click node_ratelimit "https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/ratelimit.py"
click node_chaos "https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/chaos.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_notebook,node_schema,node_sync,node_resolve,node_diff,node_client,node_report,node_logs toneBlue
class node_generation,node_naming,node_template,node_stagger toneAmber
class node_api_app,node_accounts,node_discovery,node_sources,node_database,node_models toneMint
class node_auth,node_ratelimit,node_chaos toneRose
class node_operator,node_yaml toneIndigo
```

## Components

### Provisioning client

- [Notebook workflow](https://github.com/josepvco/source-provisioner/blob/main/notebooks/provision_sources.ipynb): `notebooks/provision_sources.ipynb`
- [Schema validation](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/schema.py): `src/provisioner/schema.py`
- [Sync orchestration](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/sync.py): `src/provisioner/sync.py`
- [Resolve extensions](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/extend.py): `src/provisioner/extend.py`
- [Plan diff](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/diff.py): `src/provisioner/diff.py`
- [HTTP client](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/client.py): `src/provisioner/client.py`
- [Run report](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/report.py): `src/provisioner/report.py`
- [Structured logging](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/logs.py): `src/provisioner/logs.py`

### Source generation

- [Generation pipeline](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/generate.py): `src/provisioner/generate.py`
- [Source naming](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/naming.py): `src/provisioner/naming.py`
- [Template rendering](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/template.py): `src/provisioner/template.py`
- [Schedule staggering](https://github.com/josepvco/source-provisioner/blob/main/src/provisioner/stagger.py): `src/provisioner/stagger.py`

### Mock platform

- [API application](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/main.py): `api/mock_platform/main.py`
- [Account routes](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/routes/accounts.py): `api/mock_platform/routes/accounts.py`
- [Seeded account data](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/discovery.py): `api/mock_platform/discovery.py`
- [Source CRUD routes](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/routes/sources.py): `api/mock_platform/routes/sources.py`
- [SQLite storage](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/db.py): `api/mock_platform/db.py`
- [API data models](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/models.py): `api/mock_platform/models.py`

### Platform controls

- [Bearer authentication](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/auth.py): `api/mock_platform/auth.py`
- [Rate limiting](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/ratelimit.py): `api/mock_platform/ratelimit.py`
- [Fault injection](https://github.com/josepvco/source-provisioner/blob/main/api/mock_platform/chaos.py): `api/mock_platform/chaos.py`

### Other components

- **Operator**
- **Desired-state YAML**

## Connections

- Operator → Notebook workflow: runs workflow (evidence: `README.md`)
- Desired-state YAML → Notebook workflow: provides desired state (evidence: `README.md`)
- Notebook workflow → Schema validation: loads and validates (evidence: `README.md`)
- Notebook workflow → Sync orchestration: invokes sync (evidence: `README.md`)
- Sync orchestration → Resolve extensions: resolves sources (evidence: `src/provisioner/sync.py`)
- Resolve extensions → Generation pipeline: runs discoverers (evidence: `src/provisioner/generate.py`)
- Generation pipeline → HTTP client: lists accounts (evidence: `src/provisioner/generate.py`)
- Generation pipeline → Template rendering: renders payloads (evidence: `src/provisioner/generate.py`)
- Generation pipeline → Source naming: builds names (evidence: `src/provisioner/generate.py`)
- Generation pipeline → Schedule staggering: computes schedules (evidence: `src/provisioner/generate.py`)
- Sync orchestration → Plan diff: plans changes (evidence: `src/provisioner/sync.py`)
- Sync orchestration → HTTP client: reads and applies (evidence: `src/provisioner/sync.py`)
- Sync orchestration → Run report: records outcomes (evidence: `src/provisioner/sync.py`)
- Sync orchestration → Structured logging: logs run (evidence: `src/provisioner/sync.py`)
- HTTP client → API application: calls platform API (evidence: `README.md`)
- API application → Account routes: mounts routes (evidence: `api/mock_platform/main.py`)
- API application → Source CRUD routes: mounts routes (evidence: `api/mock_platform/main.py`)
- API application → SQLite storage: initializes database (evidence: `api/mock_platform/main.py`)
- API application → Rate limiting: configures limiter (evidence: `api/mock_platform/main.py`)
- API application → Fault injection: optionally installs (evidence: `api/mock_platform/main.py`)
- Account routes → Seeded account data: lists accounts (evidence: `api/mock_platform/routes/accounts.py`)
- Source CRUD routes → Bearer authentication: requires token (evidence: `api/mock_platform/routes/sources.py`)
- Source CRUD routes → Rate limiting: enforces limits (evidence: `api/mock_platform/routes/sources.py`)
- Source CRUD routes → SQLite storage: reads and writes (evidence: `api/mock_platform/routes/sources.py`)
- Source CRUD routes → API data models: uses request models (evidence: `api/mock_platform/routes/sources.py`)
- Account routes → Bearer authentication: requires token (evidence: `api/mock_platform/routes/accounts.py`)
- Account routes → Rate limiting: enforces limits (evidence: `api/mock_platform/routes/accounts.py`)
