# ua-academy-projects/push-and-pray architecture

> Architecture diagram of the GitHub repository ua-academy-projects/push-and-pray, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ua-academy-projects/push-and-pray
- Repository: https://github.com/ua-academy-projects/push-and-pray

## Overview

Oil Price Tracker collects WTI, Brent, and RBOB prices on a UTC schedule, persists them through a durable queue, and presents saved market data and interactive analysis in a browser. The principal path is Fetcher → PGMQ → History → PostgreSQL; browser reads and preferences pass through the UI Service. The README documents chart controls, retry/idempotency behavior, and session expiry. History’s consumer implementation was not sampled, so its documented queue and persistence actions are shown without inferring internal call details.

Main entry points: [`services/ui/backend/src/ui_service/main.py`](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/backend/src/ui_service/main.py) (UI Service), [`database/migrations`](https://github.com/ua-academy-projects/push-and-pray/tree/main/database/migrations) (PostgreSQL), [`infrastructure/ansible/oilscope/platform/roles/compose_project`](https://github.com/ua-academy-projects/push-and-pray/tree/main/infrastructure/ansible/oilscope/platform/roles/compose_project) (Compose deployment), [`services/fetcher/internal/service/service.go`](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/internal/service/service.go) (Collection service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Price collection"]
  node_schedule["UTC schedule<br/>[schedule.go]"]
  node_fetcher["Fetcher runtime<br/>[main.go]"]
  node_collector["Collection service<br/>[service.go]"]
  node_provider["Price provider<br/>[provider.go]"]
  node_publisher["PGMQ publisher<br/>[publisher.go]"]
end

subgraph group_history["History and storage"]
  node_queue["PGMQ queue"]
  node_history_consumer["History consumer<br/>[messaging.py]"]
  node_history_api["History API<br/>[main.py]"]
  node_repository["Observation repository<br/>[repository.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_presentation["Browser experience"]
  node_ui_backend["UI Service<br/>[main.py]"]
  node_session_store["Session store<br/>[session_store.py]"]
  node_frontend["React application<br/>[App.tsx]"]
  node_api_client["Frontend API client<br/>[api.ts]"]
  node_charts["Interactive charts<br/>[ChartPanel.tsx]"]
end

subgraph group_deployment["Runtime infrastructure"]
  node_deploy["Compose deployment"]
end

node_oilprice{{"OilPriceAPI"}}
node_browser(("Research user"))

node_fetcher -->|"selects slots"| node_schedule
node_fetcher -->|"runs collection"| node_collector
node_collector -->|"fetches prices"| node_provider
node_provider -->|"requests batch"| node_oilprice
node_collector -->|"publishes observations"| node_publisher
node_publisher -->|"claims event key"| node_postgres
node_publisher -->|"sends event"| node_queue
node_queue -->|"delivers messages"| node_history_consumer
node_history_consumer -->|"persists and archives"| node_postgres
node_history_api -->|"queries observations"| node_repository
node_repository -->|"reads and writes"| node_postgres
node_browser -->|"uses analysis"| node_frontend
node_frontend -->|"loads and saves"| node_api_client
node_api_client -->|"requests data"| node_ui_backend
node_ui_backend -->|"proxies reads"| node_history_api
node_ui_backend -->|"manages preferences"| node_session_store
node_session_store -->|"reads and writes sessions"| node_postgres
node_frontend -->|"renders series"| node_charts
node_deploy -.->|"deploys service"| node_fetcher
node_deploy -.->|"deploys service"| node_history_api
node_deploy -.->|"deploys service"| node_ui_backend

click node_schedule "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/internal/schedule/schedule.go"
click node_fetcher "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/cmd/fetcher/main.go"
click node_collector "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/internal/service/service.go"
click node_provider "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/internal/provider/provider.go"
click node_publisher "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/internal/pgmq/publisher.go"
click node_queue "https://github.com/ua-academy-projects/push-and-pray/blob/main/database/migrations/004_create_pgmq_queue.sql"
click node_history_consumer "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/history/src/history_service/messaging.py"
click node_history_api "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/history/src/history_service/main.py"
click node_repository "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/history/src/history_service/repository.py"
click node_postgres "https://github.com/ua-academy-projects/push-and-pray/tree/main/database/migrations"
click node_ui_backend "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/backend/src/ui_service/main.py"
click node_session_store "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/backend/src/ui_service/session_store.py"
click node_frontend "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/frontend/src/App.tsx"
click node_api_client "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/frontend/src/api.ts"
click node_charts "https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/frontend/src/ChartPanel.tsx"
click node_deploy "https://github.com/ua-academy-projects/push-and-pray/tree/main/infrastructure/ansible/oilscope/platform/roles/compose_project"

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_schedule,node_fetcher,node_collector,node_provider,node_publisher,node_browser toneBlue
class node_queue,node_history_consumer,node_history_api,node_repository,node_postgres toneAmber
class node_ui_backend,node_session_store,node_frontend,node_api_client,node_charts,node_oilprice toneMint
class node_deploy toneRose
```

## Components

### Price collection

- [UTC schedule](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/internal/schedule/schedule.go): `services/fetcher/internal/schedule/schedule.go`
- [Fetcher runtime](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/cmd/fetcher/main.go): `services/fetcher/cmd/fetcher/main.go`
- [Collection service](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/internal/service/service.go): `services/fetcher/internal/service/service.go`
- [Price provider](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/internal/provider/provider.go): `services/fetcher/internal/provider/provider.go`
- [PGMQ publisher](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/fetcher/internal/pgmq/publisher.go): `services/fetcher/internal/pgmq/publisher.go`

### History and storage

- [PGMQ queue](https://github.com/ua-academy-projects/push-and-pray/blob/main/database/migrations/004_create_pgmq_queue.sql): `database/migrations/004_create_pgmq_queue.sql`
- [History consumer](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/history/src/history_service/messaging.py): `services/history/src/history_service/messaging.py`
- [History API](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/history/src/history_service/main.py): `services/history/src/history_service/main.py`
- [Observation repository](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/history/src/history_service/repository.py): `services/history/src/history_service/repository.py`
- [PostgreSQL](https://github.com/ua-academy-projects/push-and-pray/tree/main/database/migrations): `database/migrations`

### Browser experience

- [UI Service](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/backend/src/ui_service/main.py): `services/ui/backend/src/ui_service/main.py`
- [Session store](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/backend/src/ui_service/session_store.py): `services/ui/backend/src/ui_service/session_store.py`
- [React application](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/frontend/src/App.tsx): `services/ui/frontend/src/App.tsx`
- [Frontend API client](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/frontend/src/api.ts): `services/ui/frontend/src/api.ts`
- [Interactive charts](https://github.com/ua-academy-projects/push-and-pray/blob/main/services/ui/frontend/src/ChartPanel.tsx): `services/ui/frontend/src/ChartPanel.tsx`

### Runtime infrastructure

- [Compose deployment](https://github.com/ua-academy-projects/push-and-pray/tree/main/infrastructure/ansible/oilscope/platform/roles/compose_project): `infrastructure/ansible/oilscope/platform/roles/compose_project`

### Other components

- **OilPriceAPI**
- **Research user**

## Connections

- Fetcher runtime → UTC schedule: selects slots
- Fetcher runtime → Collection service: runs collection
- Collection service → Price provider: fetches prices
- Price provider → OilPriceAPI: requests batch
- Collection service → PGMQ publisher: publishes observations
- PGMQ publisher → PostgreSQL: claims event key
- PGMQ publisher → PGMQ queue: sends event
- PGMQ queue → History consumer: delivers messages
- History consumer → PostgreSQL: persists and archives
- History API → Observation repository: queries observations
- Observation repository → PostgreSQL: reads and writes
- Research user → React application: uses analysis
- React application → Frontend API client: loads and saves
- Frontend API client → UI Service: requests data
- UI Service → History API: proxies reads
- UI Service → Session store: manages preferences
- Session store → PostgreSQL: reads and writes sessions
- React application → Interactive charts: renders series
- Compose deployment → Fetcher runtime: deploys service
- Compose deployment → History API: deploys service
- Compose deployment → UI Service: deploys service