# dnmitev/hire-wire architecture

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

- Interactive diagram: https://gitdiagram.com/dnmitev/hire-wire
- Repository: https://github.com/dnmitev/hire-wire

## Overview

hire-wire is an invoicing service: a person creates an invoice over HTTP, approves or rejects it, and retrieves its status; a Temporal workflow coordinates the decision and, on approval, payment. Postgres stores invoices, while worker activities perform conditional status changes and charge through a fake idempotent gateway. The README documents list, health, and payment-decline behavior. Edges reflect the excerpts and README; migration-to-schema wiring is documented only at the package level, so the SQL schema is shown without an asserted runner edge.

Main entry points: [`apps/api/src/routes/invoices.ts`](https://github.com/dnmitev/hire-wire/blob/main/apps/api/src/routes/invoices.ts) (Invoice routes), [`apps/api/src/app.ts`](https://github.com/dnmitev/hire-wire/blob/main/apps/api/src/app.ts) (API app), [`apps/worker/src/activities.ts`](https://github.com/dnmitev/hire-wire/blob/main/apps/worker/src/activities.ts) (Invoice activities), [`apps/worker/src/worker.ts`](https://github.com/dnmitev/hire-wire/blob/main/apps/worker/src/worker.ts) (Worker runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_api_app["API app<br/>[app.ts]"]
  node_invoice_routes["Invoice routes<br/>[invoices.ts]"]
  node_api_server["API server<br/>[server.ts]"]
end

subgraph group_workflow["Workflow orchestration"]
  node_workflow_defs["Workflow definitions<br/>[definitions.ts]"]
  node_invoice_workflow["Invoice lifecycle<br/>[workflows.ts]"]
end

subgraph group_worker["Worker and payments"]
  node_worker_runtime["Worker runtime<br/>[worker.ts]"]
  node_activities["Invoice activities<br/>[activities.ts]"]
  node_payment_gateway["Fake payment gateway<br/>[payment-gateway.ts]"]
end

subgraph group_storage["Persistence"]
  node_db_repo["Invoice repository<br/>[invoices.ts]"]
  node_db_pool["Postgres pool<br/>[pool.ts]"]
  node_migrations["Migration runner<br/>[migrate.ts]"]
  node_schema["Invoice schema<br/>[001_invoices.sql]"]
end

node_person(("Invoice user"))
node_temporal{{"Temporal service"}}
node_postgres[("Postgres")]

node_person -->|"sends requests"| node_api_app
node_api_server -->|"builds"| node_api_app
node_api_app -->|"registers"| node_invoice_routes
node_api_app -->|"checks health"| node_postgres
node_invoice_routes -->|"reads and writes"| node_db_repo
node_invoice_routes -->|"starts and updates"| node_temporal
node_invoice_routes -->|"uses update definitions"| node_workflow_defs
node_invoice_workflow -->|"registers handlers"| node_workflow_defs
node_invoice_workflow -->|"dispatches activities"| node_activities
node_worker_runtime -->|"runs worker"| node_temporal
node_worker_runtime -->|"registers activities"| node_activities
node_worker_runtime -->|"creates gateway"| node_payment_gateway
node_activities -->|"changes invoice status"| node_db_repo
node_activities -->|"charges invoice"| node_payment_gateway
node_db_repo -->|"queries and updates"| node_postgres
node_db_pool -->|"creates connection pool"| node_postgres
node_migrations -->|"uses pool"| node_db_pool

click node_api_app "https://github.com/dnmitev/hire-wire/blob/main/apps/api/src/app.ts"
click node_invoice_routes "https://github.com/dnmitev/hire-wire/blob/main/apps/api/src/routes/invoices.ts"
click node_api_server "https://github.com/dnmitev/hire-wire/blob/main/apps/api/src/server.ts"
click node_workflow_defs "https://github.com/dnmitev/hire-wire/blob/main/packages/workflows/src/definitions.ts"
click node_invoice_workflow "https://github.com/dnmitev/hire-wire/blob/main/packages/workflows/src/workflows.ts"
click node_worker_runtime "https://github.com/dnmitev/hire-wire/blob/main/apps/worker/src/worker.ts"
click node_activities "https://github.com/dnmitev/hire-wire/blob/main/apps/worker/src/activities.ts"
click node_payment_gateway "https://github.com/dnmitev/hire-wire/blob/main/apps/worker/src/payment-gateway.ts"
click node_db_repo "https://github.com/dnmitev/hire-wire/blob/main/packages/db/src/invoices.ts"
click node_db_pool "https://github.com/dnmitev/hire-wire/blob/main/packages/db/src/pool.ts"
click node_migrations "https://github.com/dnmitev/hire-wire/blob/main/packages/db/src/migrate.ts"
click node_schema "https://github.com/dnmitev/hire-wire/blob/main/packages/db/migrations/001_invoices.sql"

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_app,node_invoice_routes,node_api_server,node_person toneBlue
class node_workflow_defs,node_invoice_workflow,node_postgres toneAmber
class node_worker_runtime,node_activities,node_payment_gateway toneMint
class node_db_repo,node_db_pool,node_migrations,node_schema toneRose
class node_temporal toneIndigo
```

## Components

### HTTP API

- [API app](https://github.com/dnmitev/hire-wire/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Invoice routes](https://github.com/dnmitev/hire-wire/blob/main/apps/api/src/routes/invoices.ts): `apps/api/src/routes/invoices.ts`
- [API server](https://github.com/dnmitev/hire-wire/blob/main/apps/api/src/server.ts): `apps/api/src/server.ts`

### Workflow orchestration

- [Workflow definitions](https://github.com/dnmitev/hire-wire/blob/main/packages/workflows/src/definitions.ts): `packages/workflows/src/definitions.ts`
- [Invoice lifecycle](https://github.com/dnmitev/hire-wire/blob/main/packages/workflows/src/workflows.ts): `packages/workflows/src/workflows.ts`

### Worker and payments

- [Worker runtime](https://github.com/dnmitev/hire-wire/blob/main/apps/worker/src/worker.ts): `apps/worker/src/worker.ts`
- [Invoice activities](https://github.com/dnmitev/hire-wire/blob/main/apps/worker/src/activities.ts): `apps/worker/src/activities.ts`
- [Fake payment gateway](https://github.com/dnmitev/hire-wire/blob/main/apps/worker/src/payment-gateway.ts): `apps/worker/src/payment-gateway.ts`

### Persistence

- [Invoice repository](https://github.com/dnmitev/hire-wire/blob/main/packages/db/src/invoices.ts): `packages/db/src/invoices.ts`
- [Postgres pool](https://github.com/dnmitev/hire-wire/blob/main/packages/db/src/pool.ts): `packages/db/src/pool.ts`
- [Migration runner](https://github.com/dnmitev/hire-wire/blob/main/packages/db/src/migrate.ts): `packages/db/src/migrate.ts`
- [Invoice schema](https://github.com/dnmitev/hire-wire/blob/main/packages/db/migrations/001_invoices.sql): `packages/db/migrations/001_invoices.sql`

### Other components

- **Invoice user**
- **Temporal service**
- **Postgres**

## Connections

- Invoice user → API app: sends requests (evidence: `README.md`)
- API server → API app: builds (evidence: `apps/api/src/server.ts`)
- API app → Invoice routes: registers (evidence: `apps/api/src/app.ts`)
- API app → Postgres: checks health (evidence: `apps/api/src/app.ts`)
- Invoice routes → Invoice repository: reads and writes (evidence: `apps/api/src/routes/invoices.ts`)
- Invoice routes → Temporal service: starts and updates (evidence: `apps/api/src/routes/invoices.ts`)
- Invoice routes → Workflow definitions: uses update definitions (evidence: `apps/api/src/routes/invoices.ts`)
- Invoice lifecycle → Workflow definitions: registers handlers (evidence: `packages/workflows/src/workflows.ts`)
- Invoice lifecycle → Invoice activities: dispatches activities (evidence: `packages/workflows/src/workflows.ts`)
- Worker runtime → Temporal service: runs worker (evidence: `apps/worker/src/worker.ts`)
- Worker runtime → Invoice activities: registers activities (evidence: `apps/worker/src/worker.ts`)
- Worker runtime → Fake payment gateway: creates gateway (evidence: `apps/worker/src/worker.ts`)
- Invoice activities → Invoice repository: changes invoice status (evidence: `apps/worker/src/activities.ts`)
- Invoice activities → Fake payment gateway: charges invoice (evidence: `apps/worker/src/activities.ts`)
- Invoice repository → Postgres: queries and updates (evidence: `packages/db/src/invoices.ts`)
- Postgres pool → Postgres: creates connection pool (evidence: `packages/db/src/pool.ts`)
- Migration runner → Postgres pool: uses pool (evidence: `packages/db/src/migrate.ts`)
