# drowlands60/poles-apart architecture

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

- Interactive diagram: https://gitdiagram.com/drowlands60/poles-apart
- Repository: https://github.com/drowlands60/poles-apart

## Overview

Poles Apart is a Next.js operations app for managing customers, recurring rounds, scheduled cleaning runs, field completion, and payments. Staff work from dashboard pages and forms; run details assemble customers and rounds, while the round view supports completion, skipping, notes, and reordering. Payment screens track due and received charges. Supabase provides application data and authentication; Twilio-backed SMS, geocoding, and JSON backup are additional capabilities visible in the tree. Several feature implementations are unsampled, so their internal data flows are not expanded here.

Main entry points: [`src/lib/supabase/server.ts`](https://github.com/drowlands60/poles-apart/blob/main/src/lib/supabase/server.ts) (Server Supabase client), [`src/app/dashboard/payments/actions.ts`](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/payments/actions.ts) (Payment operations), [`src/app/dashboard/customers`](https://github.com/drowlands60/poles-apart/tree/main/src/app/dashboard/customers) (Customer screens), [`src/app/dashboard/runs`](https://github.com/drowlands60/poles-apart/tree/main/src/app/dashboard/runs) (Run screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Customer &amp; Rounds"]
  node_customers["Customer records<br/>[actions.ts]"]
  node_customer_ui["Customer screens"]
  node_rounds["Round management<br/>[actions.ts]"]
  node_round_ui["Round screens"]
  node_cleaners["Cleaner management<br/>[actions.ts]"]
end

subgraph group_field["Run Operations"]
  node_run_actions["Run management<br/>[actions.ts]"]
  node_run_ui["Run screens"]
  node_round_view_actions["Field updates<br/>[actions.ts]"]
  node_round_view_ui["Field workflow"]
  node_run_map["Run map<br/>[run-map.tsx]"]
end

subgraph group_finance["Payments"]
  node_payments_actions["Payment operations<br/>[actions.ts]"]
  node_payments_ui["Payment screens"]
  node_charge_ui["Add customer charge"]
end

subgraph group_platform["Platform Services"]
  node_login["Login<br/>[login-form.tsx]"]
  node_auth_routes["Auth routes<br/>[route.ts]"]
  node_middleware["Session middleware<br/>[middleware.ts]"]
  node_server_client["Server Supabase client<br/>[server.ts]"]
  node_browser_client["Browser Supabase client<br/>[client.ts]"]
  node_admin_client["Admin Supabase client<br/>[admin.ts]"]
  node_geocode_api["Geocode cache API<br/>[route.ts]"]
  node_backup_api["Backup API<br/>[route.ts]"]
  node_sms["SMS service<br/>[sms.ts]"]
end

node_staff(("Staff"))
node_supabase[("Supabase")]

node_staff -->|"signs in"| node_login
node_login -->|"authenticates with"| node_browser_client
node_auth_routes -->|"creates client"| node_server_client
node_middleware -->|"refreshes session"| node_server_client
node_customers -->|"creates client"| node_server_client
node_customer_ui -->|"invokes actions"| node_customers
node_customer_ui -->|"renders"| node_charge_ui
node_charge_ui -->|"calls"| node_payments_actions
node_rounds -->|"creates client"| node_server_client
node_round_ui -->|"invokes actions"| node_rounds
node_cleaners -.->|"creates client"| node_server_client
node_run_actions -->|"creates client"| node_server_client
node_run_ui -->|"calls"| node_run_actions
node_round_view_ui -->|"calls"| node_round_view_actions
node_round_view_ui -->|"uses"| node_run_map
node_round_view_actions -->|"creates client"| node_server_client
node_payments_ui -->|"calls"| node_payments_actions
node_payments_actions -->|"creates client"| node_server_client
node_server_client -.->|"connects to"| node_supabase
node_browser_client -.->|"connects to"| node_supabase
node_geocode_api -->|"creates client"| node_server_client
node_backup_api -->|"creates client"| node_admin_client
node_staff -.->|"requests export"| node_backup_api
node_run_ui -.->|"sends messages"| node_sms

click node_customers "https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/customers/actions.ts"
click node_customer_ui "https://github.com/drowlands60/poles-apart/tree/main/src/app/dashboard/customers"
click node_rounds "https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/rounds/actions.ts"
click node_round_ui "https://github.com/drowlands60/poles-apart/tree/main/src/app/dashboard/rounds"
click node_cleaners "https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/cleaners/actions.ts"
click node_run_actions "https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/runs/actions.ts"
click node_run_ui "https://github.com/drowlands60/poles-apart/tree/main/src/app/dashboard/runs"
click node_round_view_actions "https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/round-view/actions.ts"
click node_round_view_ui "https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/round-view/round-view-client.tsx"
click node_run_map "https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/runs/%5Bid%5D/run-map.tsx"
click node_payments_actions "https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/payments/actions.ts"
click node_payments_ui "https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/payments/payments-client.tsx"
click node_charge_ui "https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/customers/add-charge-button.tsx"
click node_login "https://github.com/drowlands60/poles-apart/blob/main/src/app/login/login-form.tsx"
click node_auth_routes "https://github.com/drowlands60/poles-apart/blob/main/src/app/auth/callback/route.ts"
click node_middleware "https://github.com/drowlands60/poles-apart/blob/main/src/middleware.ts"
click node_server_client "https://github.com/drowlands60/poles-apart/blob/main/src/lib/supabase/server.ts"
click node_browser_client "https://github.com/drowlands60/poles-apart/blob/main/src/lib/supabase/client.ts"
click node_admin_client "https://github.com/drowlands60/poles-apart/blob/main/src/lib/supabase/admin.ts"
click node_geocode_api "https://github.com/drowlands60/poles-apart/blob/main/src/app/api/geocode-cache/route.ts"
click node_backup_api "https://github.com/drowlands60/poles-apart/blob/main/src/app/api/backup/route.ts"
click node_sms "https://github.com/drowlands60/poles-apart/blob/main/src/lib/sms.ts"

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_customers,node_customer_ui,node_rounds,node_round_ui,node_cleaners toneBlue
class node_run_actions,node_run_ui,node_round_view_actions,node_round_view_ui,node_run_map,node_supabase toneAmber
class node_payments_actions,node_payments_ui,node_charge_ui toneMint
class node_login,node_auth_routes,node_middleware,node_server_client,node_browser_client,node_admin_client,node_geocode_api,node_backup_api,node_sms toneRose
class node_staff toneIndigo
```

## Components

### Customer & Rounds

- [Customer records](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/customers/actions.ts): `src/app/dashboard/customers/actions.ts`
- [Customer screens](https://github.com/drowlands60/poles-apart/tree/main/src/app/dashboard/customers): `src/app/dashboard/customers`
- [Round management](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/rounds/actions.ts): `src/app/dashboard/rounds/actions.ts`
- [Round screens](https://github.com/drowlands60/poles-apart/tree/main/src/app/dashboard/rounds): `src/app/dashboard/rounds`
- [Cleaner management](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/cleaners/actions.ts): `src/app/dashboard/cleaners/actions.ts`

### Run Operations

- [Run management](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/runs/actions.ts): `src/app/dashboard/runs/actions.ts`
- [Run screens](https://github.com/drowlands60/poles-apart/tree/main/src/app/dashboard/runs): `src/app/dashboard/runs`
- [Field updates](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/round-view/actions.ts): `src/app/dashboard/round-view/actions.ts`
- [Field workflow](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/round-view/round-view-client.tsx): `src/app/dashboard/round-view/round-view-client.tsx`
- [Run map](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/runs/%5Bid%5D/run-map.tsx): `src/app/dashboard/runs/[id]/run-map.tsx`

### Payments

- [Payment operations](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/payments/actions.ts): `src/app/dashboard/payments/actions.ts`
- [Payment screens](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/payments/payments-client.tsx): `src/app/dashboard/payments/payments-client.tsx`
- [Add customer charge](https://github.com/drowlands60/poles-apart/blob/main/src/app/dashboard/customers/add-charge-button.tsx): `src/app/dashboard/customers/add-charge-button.tsx`

### Platform Services

- [Login](https://github.com/drowlands60/poles-apart/blob/main/src/app/login/login-form.tsx): `src/app/login/login-form.tsx`
- [Auth routes](https://github.com/drowlands60/poles-apart/blob/main/src/app/auth/callback/route.ts): `src/app/auth/callback/route.ts`
- [Session middleware](https://github.com/drowlands60/poles-apart/blob/main/src/middleware.ts): `src/middleware.ts`
- [Server Supabase client](https://github.com/drowlands60/poles-apart/blob/main/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- [Browser Supabase client](https://github.com/drowlands60/poles-apart/blob/main/src/lib/supabase/client.ts): `src/lib/supabase/client.ts`
- [Admin Supabase client](https://github.com/drowlands60/poles-apart/blob/main/src/lib/supabase/admin.ts): `src/lib/supabase/admin.ts`
- [Geocode cache API](https://github.com/drowlands60/poles-apart/blob/main/src/app/api/geocode-cache/route.ts): `src/app/api/geocode-cache/route.ts`
- [Backup API](https://github.com/drowlands60/poles-apart/blob/main/src/app/api/backup/route.ts): `src/app/api/backup/route.ts`
- [SMS service](https://github.com/drowlands60/poles-apart/blob/main/src/lib/sms.ts): `src/lib/sms.ts`

### Other components

- **Staff**
- **Supabase**

## Connections

- Staff → Login: signs in
- Login → Browser Supabase client: authenticates with (evidence: `src/app/login/login-form.tsx`)
- Auth routes → Server Supabase client: creates client (evidence: `src/app/auth/callback/route.ts`)
- Session middleware → Server Supabase client: refreshes session (evidence: `src/middleware.ts`)
- Customer records → Server Supabase client: creates client (evidence: `src/app/dashboard/customers/actions.ts`)
- Customer screens → Customer records: invokes actions (evidence: `src/app/dashboard/customers/[id]/page.tsx`)
- Customer screens → Add customer charge: renders (evidence: `src/app/dashboard/customers/[id]/page.tsx`)
- Add customer charge → Payment operations: calls (evidence: `src/app/dashboard/customers/add-charge-button.tsx`)
- Round management → Server Supabase client: creates client (evidence: `src/app/dashboard/rounds/actions.ts`)
- Round screens → Round management: invokes actions (evidence: `src/app/dashboard/rounds/[id]/page.tsx`)
- Cleaner management → Server Supabase client: creates client
- Run management → Server Supabase client: creates client (evidence: `src/app/dashboard/runs/actions.ts`)
- Run screens → Run management: calls (evidence: `src/app/dashboard/runs/[id]/run-detail-client.tsx`)
- Field workflow → Field updates: calls (evidence: `src/app/dashboard/round-view/round-view-client.tsx`)
- Field workflow → Run map: uses (evidence: `src/app/dashboard/round-view/round-view-client.tsx`)
- Field updates → Server Supabase client: creates client (evidence: `src/app/dashboard/round-view/actions.ts`)
- Payment screens → Payment operations: calls (evidence: `src/app/dashboard/payments/payments-client.tsx`)
- Payment operations → Server Supabase client: creates client (evidence: `src/app/dashboard/payments/actions.ts`)
- Server Supabase client → Supabase: connects to
- Browser Supabase client → Supabase: connects to
- Geocode cache API → Server Supabase client: creates client (evidence: `src/app/api/geocode-cache/route.ts`)
- Backup API → Admin Supabase client: creates client (evidence: `src/app/api/backup/route.ts`)
- Staff → Backup API: requests export (evidence: `src/app/api/backup/route.ts`)
- Run screens → SMS service: sends messages
