# ilyassultanov/sync-service architecture

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

- Interactive diagram: https://gitdiagram.com/ilyassultanov/sync-service
- Repository: https://github.com/ilyassultanov/sync-service

## Overview

Sync Service is a FastAPI backend that transfers records from internal system A to system B, supports manual and scheduled runs, and exposes run history, status, details, and errors. The principal workflow is API or scheduler → run creation → background execution → source fetch → per-record target push → persisted snapshots and results → API monitoring. The graph distinguishes orchestration, integrations, API contracts, and persistence. HTTP clients are documented as drop-in alternatives; their runtime wiring is not shown in the excerpts.

Main entry points: [`app/api/routes/syncs.py`](https://github.com/ilyassultanov/sync-service/blob/main/app/api/routes/syncs.py) (Sync endpoints), [`app/services/sync_service.py`](https://github.com/ilyassultanov/sync-service/blob/main/app/services/sync_service.py) (Sync service), [`app/workers/scheduler.py`](https://github.com/ilyassultanov/sync-service/blob/main/app/workers/scheduler.py) (Periodic scheduler), [`app/repositories/sync_repository.py`](https://github.com/ilyassultanov/sync-service/blob/main/app/repositories/sync_repository.py) (Sync repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and contracts"]
  node_api["Sync endpoints<br/>[syncs.py]"]
  node_schemas["API schemas<br/>[sync.py]"]
  node_app_lifecycle["App lifecycle<br/>[main.py]"]
end

subgraph group_execution["Sync execution"]
  node_service["Sync service<br/>[sync_service.py]"]
  node_tasks["Task runner<br/>[tasks.py]"]
  node_scheduler["Periodic scheduler<br/>[scheduler.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_integrations["System integrations"]
  node_client_interfaces["Client interfaces<br/>[base.py]"]
  node_mock_source["Mock source client<br/>[system_a_mock.py]"]
  node_mock_target["Mock target client<br/>[system_b_mock.py]"]
  node_http_clients["HTTP clients<br/>[http_clients.py]"]
end

subgraph group_persistence["Persistence"]
  node_repository["Sync repository<br/>[sync_repository.py]"]
  node_models["Run and item models<br/>[sync_run.py]"]
  node_db_session["Async DB session<br/>[base.py]"]
end

node_operator(("API caller"))
node_system_a["System A"]
node_system_b["System B"]
node_postgres[("PostgreSQL")]

node_operator -->|"calls endpoints"| node_api
node_api -->|"starts runs"| node_service
node_api -->|"schedules task"| node_tasks
node_api -->|"queries runs"| node_repository
node_api -->|"shapes responses"| node_schemas
node_app_lifecycle -->|"registers routes"| node_api
node_app_lifecycle -->|"starts scheduler"| node_scheduler
node_scheduler -->|"creates scheduled run"| node_service
node_scheduler -->|"runs task"| node_tasks
node_tasks -->|"executes run"| node_service
node_service -->|"reads and writes"| node_repository
node_service -->|"uses clients"| node_client_interfaces
node_service -->|"defaults to"| node_mock_source
node_service -->|"defaults to"| node_mock_target
node_mock_source -->|"fetches records"| node_system_a
node_mock_target -->|"pushes records"| node_system_b
node_http_clients -.->|"fetches records"| node_system_a
node_http_clients -.->|"pushes records"| node_system_b
node_repository -->|"manages records"| node_models
node_api -->|"obtains session"| node_db_session
node_db_session -->|"connects to"| node_postgres
node_repository -->|"persists run data"| node_postgres
node_scheduler -->|"reads interval"| node_settings
node_db_session -->|"reads database URL"| node_settings

click node_api "https://github.com/ilyassultanov/sync-service/blob/main/app/api/routes/syncs.py"
click node_schemas "https://github.com/ilyassultanov/sync-service/blob/main/app/schemas/sync.py"
click node_app_lifecycle "https://github.com/ilyassultanov/sync-service/blob/main/app/main.py"
click node_service "https://github.com/ilyassultanov/sync-service/blob/main/app/services/sync_service.py"
click node_tasks "https://github.com/ilyassultanov/sync-service/blob/main/app/workers/tasks.py"
click node_scheduler "https://github.com/ilyassultanov/sync-service/blob/main/app/workers/scheduler.py"
click node_settings "https://github.com/ilyassultanov/sync-service/blob/main/app/config.py"
click node_client_interfaces "https://github.com/ilyassultanov/sync-service/blob/main/app/integrations/base.py"
click node_mock_source "https://github.com/ilyassultanov/sync-service/blob/main/app/integrations/system_a_mock.py"
click node_mock_target "https://github.com/ilyassultanov/sync-service/blob/main/app/integrations/system_b_mock.py"
click node_http_clients "https://github.com/ilyassultanov/sync-service/blob/main/app/integrations/http_clients.py"
click node_repository "https://github.com/ilyassultanov/sync-service/blob/main/app/repositories/sync_repository.py"
click node_models "https://github.com/ilyassultanov/sync-service/blob/main/app/db/models/sync_run.py"
click node_db_session "https://github.com/ilyassultanov/sync-service/blob/main/app/db/base.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_api,node_schemas,node_app_lifecycle toneBlue
class node_service,node_tasks,node_scheduler,node_settings,node_postgres toneAmber
class node_client_interfaces,node_mock_source,node_mock_target,node_http_clients,node_operator toneMint
class node_repository,node_models,node_db_session toneRose
class node_system_a,node_system_b toneIndigo
```

## Components

### API and contracts

- [Sync endpoints](https://github.com/ilyassultanov/sync-service/blob/main/app/api/routes/syncs.py): `app/api/routes/syncs.py`
- [API schemas](https://github.com/ilyassultanov/sync-service/blob/main/app/schemas/sync.py): `app/schemas/sync.py`
- [App lifecycle](https://github.com/ilyassultanov/sync-service/blob/main/app/main.py): `app/main.py`

### Sync execution

- [Sync service](https://github.com/ilyassultanov/sync-service/blob/main/app/services/sync_service.py): `app/services/sync_service.py`
- [Task runner](https://github.com/ilyassultanov/sync-service/blob/main/app/workers/tasks.py): `app/workers/tasks.py`
- [Periodic scheduler](https://github.com/ilyassultanov/sync-service/blob/main/app/workers/scheduler.py): `app/workers/scheduler.py`
- [Runtime settings](https://github.com/ilyassultanov/sync-service/blob/main/app/config.py): `app/config.py`

### System integrations

- [Client interfaces](https://github.com/ilyassultanov/sync-service/blob/main/app/integrations/base.py): `app/integrations/base.py`
- [Mock source client](https://github.com/ilyassultanov/sync-service/blob/main/app/integrations/system_a_mock.py): `app/integrations/system_a_mock.py`
- [Mock target client](https://github.com/ilyassultanov/sync-service/blob/main/app/integrations/system_b_mock.py): `app/integrations/system_b_mock.py`
- [HTTP clients](https://github.com/ilyassultanov/sync-service/blob/main/app/integrations/http_clients.py): `app/integrations/http_clients.py`

### Persistence

- [Sync repository](https://github.com/ilyassultanov/sync-service/blob/main/app/repositories/sync_repository.py): `app/repositories/sync_repository.py`
- [Run and item models](https://github.com/ilyassultanov/sync-service/blob/main/app/db/models/sync_run.py): `app/db/models/sync_run.py`
- [Async DB session](https://github.com/ilyassultanov/sync-service/blob/main/app/db/base.py): `app/db/base.py`

### Other components

- **API caller**
- **System A**
- **System B**
- **PostgreSQL**

## Connections

- API caller → Sync endpoints: calls endpoints (evidence: `README.md`)
- Sync endpoints → Sync service: starts runs (evidence: `app/api/routes/syncs.py`)
- Sync endpoints → Task runner: schedules task (evidence: `app/api/routes/syncs.py`)
- Sync endpoints → Sync repository: queries runs (evidence: `app/api/routes/syncs.py`)
- Sync endpoints → API schemas: shapes responses (evidence: `app/api/routes/syncs.py`)
- App lifecycle → Sync endpoints: registers routes (evidence: `app/main.py`)
- App lifecycle → Periodic scheduler: starts scheduler (evidence: `app/main.py`)
- Periodic scheduler → Sync service: creates scheduled run (evidence: `app/workers/scheduler.py`)
- Periodic scheduler → Task runner: runs task (evidence: `app/workers/scheduler.py`)
- Task runner → Sync service: executes run (evidence: `app/workers/tasks.py`)
- Sync service → Sync repository: reads and writes (evidence: `app/services/sync_service.py`)
- Sync service → Client interfaces: uses clients (evidence: `app/services/sync_service.py`)
- Sync service → Mock source client: defaults to (evidence: `app/services/sync_service.py`)
- Sync service → Mock target client: defaults to (evidence: `app/services/sync_service.py`)
- Mock source client → System A: fetches records (evidence: `README.md`)
- Mock target client → System B: pushes records (evidence: `README.md`)
- HTTP clients → System A: fetches records (evidence: `README.md`)
- HTTP clients → System B: pushes records (evidence: `README.md`)
- Sync repository → Run and item models: manages records (evidence: `app/repositories/sync_repository.py`)
- Sync endpoints → Async DB session: obtains session (evidence: `app/api/routes/syncs.py`)
- Async DB session → PostgreSQL: connects to (evidence: `app/db/base.py`)
- Sync repository → PostgreSQL: persists run data (evidence: `app/repositories/sync_repository.py`)
- Periodic scheduler → Runtime settings: reads interval (evidence: `app/workers/scheduler.py`)
- Async DB session → Runtime settings: reads database URL (evidence: `app/db/base.py`)
