# dawsdo/shipthacks architecture

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

- Interactive diagram: https://gitdiagram.com/dawsdo/shipthacks
- Repository: https://github.com/dawsdo/shipthacks

## Overview

ShelterLink BHM helps people find a suitable Birmingham shelter with currently confirmed open beds, then place a time-limited hold; shelter staff can report counts, pause arrivals, and check people in. The core flow is browse and filter → inspect a listing → hold a bed, with a separate host-console workflow for updating availability and handling arrivals. The README documents privacy safeguards and HUD-based seeding; source excerpts show the API and main UI calls. Some subsystem links are omitted where unsampled implementation details do not establish the relationship.

Main entry points: [`src/pages/Browse.jsx`](https://github.com/dawsdo/shipthacks/blob/main/src/pages/Browse.jsx) (Browse and filter), [`server/db.js`](https://github.com/dawsdo/shipthacks/blob/main/server/db.js) (Database access), [`src/App.jsx`](https://github.com/dawsdo/shipthacks/blob/main/src/App.jsx) (App routing), [`server/index.js`](https://github.com/dawsdo/shipthacks/blob/main/server/index.js) (Express API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Shelter discovery"]
  node_app["App routing<br/>[App.jsx]"]
  node_browse["Browse and filter<br/>[Browse.jsx]"]
  node_listing_cards["Listing cards<br/>[ListingCard.jsx]"]
  node_listing["Listing and holds<br/>[Listing.jsx]"]
  node_stepper["People stepper<br/>[Stepper.jsx]"]
  node_search_rules["Eligibility and display<br/>[lib.js]"]
end

subgraph group_host["Host operations"]
  node_host_console["Host console<br/>[Host.jsx]"]
end

subgraph group_service["API and rules"]
  node_client_api["API client<br/>[api.js]"]
  node_api_routes["Express API<br/>[index.js]"]
  node_availability_rules["Freshness and privacy<br/>[index.js]"]
  node_hold_lifecycle["Hold lifecycle<br/>[index.js]"]
end

subgraph group_data["Shelter data"]
  node_db_access["Database access<br/>[db.js]"]
  node_schema["Hosts and holds schema<br/>[schema.sql]"]
  node_postgres[("PostgreSQL")]
  node_hic_loader["HUD inventory loader<br/>[load-hic.js]"]
end

node_seeker(("Bed seeker"))
node_host_staff(("Shelter staff"))

node_seeker -->|"opens"| node_app
node_app -->|"routes to"| node_browse
node_app -->|"routes to"| node_listing
node_app -->|"routes to"| node_host_console
node_browse -->|"fetches hosts"| node_client_api
node_browse -->|"filters and sorts"| node_search_rules
node_browse -->|"renders"| node_listing_cards
node_browse -->|"renders"| node_stepper
node_listing -->|"loads and holds"| node_client_api
node_listing -->|"renders"| node_stepper
node_listing_cards -->|"formats with"| node_search_rules
node_host_staff -->|"updates beds"| node_host_console
node_host_console -->|"updates and checks in"| node_client_api
node_client_api -->|"sends API requests"| node_api_routes
node_api_routes -->|"shapes host data"| node_availability_rules
node_availability_rules -->|"queries host data"| node_db_access
node_api_routes -->|"dispatches hold actions"| node_hold_lifecycle
node_hold_lifecycle -->|"reads and writes holds"| node_db_access
node_api_routes -->|"updates host counts"| node_db_access
node_db_access -->|"initializes tables"| node_schema
node_db_access -->|"connects to"| node_postgres
node_hic_loader -.->|"loads inventory"| node_postgres

click node_app "https://github.com/dawsdo/shipthacks/blob/main/src/App.jsx"
click node_browse "https://github.com/dawsdo/shipthacks/blob/main/src/pages/Browse.jsx"
click node_listing_cards "https://github.com/dawsdo/shipthacks/blob/main/src/components/ListingCard.jsx"
click node_listing "https://github.com/dawsdo/shipthacks/blob/main/src/pages/Listing.jsx"
click node_stepper "https://github.com/dawsdo/shipthacks/blob/main/src/components/Stepper.jsx"
click node_search_rules "https://github.com/dawsdo/shipthacks/blob/main/src/lib.js"
click node_host_console "https://github.com/dawsdo/shipthacks/blob/main/src/pages/Host.jsx"
click node_client_api "https://github.com/dawsdo/shipthacks/blob/main/src/api.js"
click node_api_routes "https://github.com/dawsdo/shipthacks/blob/main/server/index.js"
click node_availability_rules "https://github.com/dawsdo/shipthacks/blob/main/server/index.js"
click node_hold_lifecycle "https://github.com/dawsdo/shipthacks/blob/main/server/index.js"
click node_db_access "https://github.com/dawsdo/shipthacks/blob/main/server/db.js"
click node_schema "https://github.com/dawsdo/shipthacks/blob/main/server/schema.sql"
click node_hic_loader "https://github.com/dawsdo/shipthacks/blob/main/server/load-hic.js"

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_app,node_browse,node_listing_cards,node_listing,node_stepper,node_search_rules toneBlue
class node_host_console toneAmber
class node_client_api,node_api_routes,node_availability_rules,node_hold_lifecycle toneMint
class node_db_access,node_schema,node_postgres,node_hic_loader toneRose
class node_seeker,node_host_staff toneIndigo
```

## Components

### Shelter discovery

- [App routing](https://github.com/dawsdo/shipthacks/blob/main/src/App.jsx): `src/App.jsx`
- [Browse and filter](https://github.com/dawsdo/shipthacks/blob/main/src/pages/Browse.jsx): `src/pages/Browse.jsx`
- [Listing cards](https://github.com/dawsdo/shipthacks/blob/main/src/components/ListingCard.jsx): `src/components/ListingCard.jsx`
- [Listing and holds](https://github.com/dawsdo/shipthacks/blob/main/src/pages/Listing.jsx): `src/pages/Listing.jsx`
- [People stepper](https://github.com/dawsdo/shipthacks/blob/main/src/components/Stepper.jsx): `src/components/Stepper.jsx`
- [Eligibility and display](https://github.com/dawsdo/shipthacks/blob/main/src/lib.js): `src/lib.js`

### Host operations

- [Host console](https://github.com/dawsdo/shipthacks/blob/main/src/pages/Host.jsx): `src/pages/Host.jsx`

### API and rules

- [API client](https://github.com/dawsdo/shipthacks/blob/main/src/api.js): `src/api.js`
- [Express API](https://github.com/dawsdo/shipthacks/blob/main/server/index.js): `server/index.js`
- [Freshness and privacy](https://github.com/dawsdo/shipthacks/blob/main/server/index.js): `server/index.js`
- [Hold lifecycle](https://github.com/dawsdo/shipthacks/blob/main/server/index.js): `server/index.js`

### Shelter data

- [Database access](https://github.com/dawsdo/shipthacks/blob/main/server/db.js): `server/db.js`
- [Hosts and holds schema](https://github.com/dawsdo/shipthacks/blob/main/server/schema.sql): `server/schema.sql`
- **PostgreSQL**
- [HUD inventory loader](https://github.com/dawsdo/shipthacks/blob/main/server/load-hic.js): `server/load-hic.js`

### Other components

- **Bed seeker**
- **Shelter staff**

## Connections

- Bed seeker → App routing: opens (evidence: `README.md`)
- App routing → Browse and filter: routes to (evidence: `src/App.jsx`)
- App routing → Listing and holds: routes to (evidence: `src/App.jsx`)
- App routing → Host console: routes to (evidence: `src/App.jsx`)
- Browse and filter → API client: fetches hosts (evidence: `src/pages/Browse.jsx`)
- Browse and filter → Eligibility and display: filters and sorts (evidence: `src/pages/Browse.jsx`)
- Browse and filter → Listing cards: renders (evidence: `src/pages/Browse.jsx`)
- Browse and filter → People stepper: renders (evidence: `src/pages/Browse.jsx`)
- Listing and holds → API client: loads and holds (evidence: `src/pages/Listing.jsx`)
- Listing and holds → People stepper: renders (evidence: `src/pages/Listing.jsx`)
- Listing cards → Eligibility and display: formats with (evidence: `src/components/ListingCard.jsx`)
- Shelter staff → Host console: updates beds (evidence: `README.md`)
- Host console → API client: updates and checks in (evidence: `src/pages/Host.jsx`)
- API client → Express API: sends API requests (evidence: `README.md`)
- Express API → Freshness and privacy: shapes host data (evidence: `server/index.js`)
- Freshness and privacy → Database access: queries host data (evidence: `server/index.js`)
- Express API → Hold lifecycle: dispatches hold actions (evidence: `server/index.js`)
- Hold lifecycle → Database access: reads and writes holds (evidence: `server/index.js`)
- Express API → Database access: updates host counts (evidence: `server/index.js`)
- Database access → Hosts and holds schema: initializes tables (evidence: `server/db.js`)
- Database access → PostgreSQL: connects to (evidence: `server/db.js`)
- HUD inventory loader → PostgreSQL: loads inventory