# kkrugley/safepaws architecture

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

- Interactive diagram: https://gitdiagram.com/kkrugley/safepaws
- Repository: https://github.com/kkrugley/safepaws

## Overview

SafePaws is a multilingual website for browsing free cat-shelter designs, downloading fabrication files, and finding nearby workshops. The main user journey runs from the product catalog to product details and downloads, then on to fabrication and assembly; the site also supports community stories and ideas, a quiz and materials calculator, workshop discovery, and user submissions. The sampled code confirms catalog rendering and workshop-search adapters, but most API and data connections were not shown, so those relationships are omitted or marked unverified.

Main entry points: [`website/src/app/solutions/SolutionsClient.tsx`](https://github.com/kkrugley/safepaws/blob/main/website/src/app/solutions/SolutionsClient.tsx) (Product catalog), [`website/src/lib/workshops.ts`](https://github.com/kkrugley/safepaws/blob/main/website/src/lib/workshops.ts) (Workshop services), [`website/src/app/solutions/find-workshop/WorkshopFinder.tsx`](https://github.com/kkrugley/safepaws/blob/main/website/src/app/solutions/find-workshop/WorkshopFinder.tsx) (Workshop search), [`website/src/lib/workshop-sources/websearch.ts`](https://github.com/kkrugley/safepaws/blob/main/website/src/lib/workshop-sources/websearch.ts) (Web search adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Product discovery"]
  node_catalog["Product catalog"]
  node_productdata["Product content<br/>[products.ts]"]
  node_productpages["Product details<br/>[page.tsx]"]
  node_quiz["Product quiz<br/>[QuizSection.tsx]"]
end

subgraph group_build["Build resources"]
  node_downloads["Download center"]
  node_materials["Materials calculator"]
  node_help["Build guidance<br/>[HelpContent.tsx]"]
end

subgraph group_community["Community"]
  node_stories["Community stories<br/>[stories.ts]"]
  node_ideas["Community ideas<br/>[ideas.ts]"]
  node_submissions["User submissions<br/>[route.ts]"]
end

subgraph group_workshops["Workshop finder"]
  node_workshopfinder["Workshop search<br/>[WorkshopFinder.tsx]"]
  node_workshops["Workshop services<br/>[workshops.ts]"]
  node_websearch["Web search adapter<br/>[websearch.ts]"]
  node_firecrawl["Firecrawl search<br/>[firecrawl.ts]"]
  node_osm["OpenStreetMap source<br/>[osm.ts]"]
end

subgraph group_platform["Website services"]
  node_downloadapi["Download endpoint<br/>[route.ts]"]
  node_geocode["Geocoding endpoint<br/>[route.ts]"]
  node_notifications["Notify subscriptions<br/>[route.ts]"]
  node_database[("Neon database<br/>[db.ts]")]
end

node_visitor(("Visitor"))

node_visitor -->|"browses"| node_catalog
node_catalog -->|"loads products"| node_productdata
node_catalog -->|"opens details"| node_productpages
node_visitor -->|"downloads files"| node_downloads
node_catalog -->|"links downloads"| node_downloads
node_visitor -->|"takes quiz"| node_quiz
node_visitor -->|"calculates materials"| node_materials
node_visitor -->|"reads instructions"| node_help
node_visitor -.->|"shares stories"| node_stories
node_visitor -.->|"submits ideas"| node_submissions
node_visitor -->|"searches workshops"| node_workshopfinder
node_workshopfinder -.->|"requests search"| node_workshops
node_workshops -.->|"uses adapter"| node_websearch
node_websearch -->|"calls search"| node_firecrawl
node_workshops -.->|"may use source"| node_osm
node_visitor -.->|"requests updates"| node_notifications
node_visitor -.->|"geocodes location"| node_geocode
node_downloadapi -.->|"may read records"| node_database

click node_catalog "https://github.com/kkrugley/safepaws/blob/main/website/src/app/solutions/SolutionsClient.tsx"
click node_productdata "https://github.com/kkrugley/safepaws/blob/main/website/src/data/products.ts"
click node_productpages "https://github.com/kkrugley/safepaws/blob/main/website/src/app/solutions/%5Bslug%5D/page.tsx"
click node_quiz "https://github.com/kkrugley/safepaws/blob/main/website/src/components/ui/QuizSection.tsx"
click node_downloads "https://github.com/kkrugley/safepaws/blob/main/website/src/app/download/DownloadContent.tsx"
click node_downloadapi "https://github.com/kkrugley/safepaws/blob/main/website/src/app/api/downloads/route.ts"
click node_materials "https://github.com/kkrugley/safepaws/blob/main/website/src/components/ui/MaterialsCalculator.tsx"
click node_help "https://github.com/kkrugley/safepaws/blob/main/website/src/app/help/HelpContent.tsx"
click node_stories "https://github.com/kkrugley/safepaws/blob/main/website/src/lib/stories.ts"
click node_ideas "https://github.com/kkrugley/safepaws/blob/main/website/src/lib/ideas.ts"
click node_workshopfinder "https://github.com/kkrugley/safepaws/blob/main/website/src/app/solutions/find-workshop/WorkshopFinder.tsx"
click node_workshops "https://github.com/kkrugley/safepaws/blob/main/website/src/lib/workshops.ts"
click node_websearch "https://github.com/kkrugley/safepaws/blob/main/website/src/lib/workshop-sources/websearch.ts"
click node_firecrawl "https://github.com/kkrugley/safepaws/blob/main/website/src/lib/workshop-sources/firecrawl.ts"
click node_osm "https://github.com/kkrugley/safepaws/blob/main/website/src/lib/workshop-sources/osm.ts"
click node_geocode "https://github.com/kkrugley/safepaws/blob/main/website/src/app/api/geocode/route.ts"
click node_submissions "https://github.com/kkrugley/safepaws/blob/main/website/src/app/api/ideas/route.ts"
click node_notifications "https://github.com/kkrugley/safepaws/blob/main/website/src/app/api/notify-subscribe/route.ts"
click node_database "https://github.com/kkrugley/safepaws/blob/main/website/src/lib/db.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_catalog,node_productdata,node_productpages,node_quiz toneBlue
class node_downloads,node_materials,node_help toneAmber
class node_stories,node_ideas,node_submissions toneMint
class node_workshopfinder,node_workshops,node_websearch,node_firecrawl,node_osm toneRose
class node_downloadapi,node_geocode,node_notifications,node_database,node_visitor toneIndigo
```

## Components

### Product discovery

- [Product catalog](https://github.com/kkrugley/safepaws/blob/main/website/src/app/solutions/SolutionsClient.tsx): `website/src/app/solutions/SolutionsClient.tsx`
- [Product content](https://github.com/kkrugley/safepaws/blob/main/website/src/data/products.ts): `website/src/data/products.ts`
- [Product details](https://github.com/kkrugley/safepaws/blob/main/website/src/app/solutions/%5Bslug%5D/page.tsx): `website/src/app/solutions/[slug]/page.tsx`
- [Product quiz](https://github.com/kkrugley/safepaws/blob/main/website/src/components/ui/QuizSection.tsx): `website/src/components/ui/QuizSection.tsx`

### Build resources

- [Download center](https://github.com/kkrugley/safepaws/blob/main/website/src/app/download/DownloadContent.tsx): `website/src/app/download/DownloadContent.tsx`
- [Materials calculator](https://github.com/kkrugley/safepaws/blob/main/website/src/components/ui/MaterialsCalculator.tsx): `website/src/components/ui/MaterialsCalculator.tsx`
- [Build guidance](https://github.com/kkrugley/safepaws/blob/main/website/src/app/help/HelpContent.tsx): `website/src/app/help/HelpContent.tsx`

### Community

- [Community stories](https://github.com/kkrugley/safepaws/blob/main/website/src/lib/stories.ts): `website/src/lib/stories.ts`
- [Community ideas](https://github.com/kkrugley/safepaws/blob/main/website/src/lib/ideas.ts): `website/src/lib/ideas.ts`
- [User submissions](https://github.com/kkrugley/safepaws/blob/main/website/src/app/api/ideas/route.ts): `website/src/app/api/ideas/route.ts`

### Workshop finder

- [Workshop search](https://github.com/kkrugley/safepaws/blob/main/website/src/app/solutions/find-workshop/WorkshopFinder.tsx): `website/src/app/solutions/find-workshop/WorkshopFinder.tsx`
- [Workshop services](https://github.com/kkrugley/safepaws/blob/main/website/src/lib/workshops.ts): `website/src/lib/workshops.ts`
- [Web search adapter](https://github.com/kkrugley/safepaws/blob/main/website/src/lib/workshop-sources/websearch.ts): `website/src/lib/workshop-sources/websearch.ts`
- [Firecrawl search](https://github.com/kkrugley/safepaws/blob/main/website/src/lib/workshop-sources/firecrawl.ts): `website/src/lib/workshop-sources/firecrawl.ts`
- [OpenStreetMap source](https://github.com/kkrugley/safepaws/blob/main/website/src/lib/workshop-sources/osm.ts): `website/src/lib/workshop-sources/osm.ts`

### Website services

- [Download endpoint](https://github.com/kkrugley/safepaws/blob/main/website/src/app/api/downloads/route.ts): `website/src/app/api/downloads/route.ts`
- [Geocoding endpoint](https://github.com/kkrugley/safepaws/blob/main/website/src/app/api/geocode/route.ts): `website/src/app/api/geocode/route.ts`
- [Notify subscriptions](https://github.com/kkrugley/safepaws/blob/main/website/src/app/api/notify-subscribe/route.ts): `website/src/app/api/notify-subscribe/route.ts`
- [Neon database](https://github.com/kkrugley/safepaws/blob/main/website/src/lib/db.ts): `website/src/lib/db.ts`

### Other components

- **Visitor**

## Connections

- Visitor → Product catalog: browses
- Product catalog → Product content: loads products (evidence: `website/src/app/solutions/SolutionsClient.tsx`)
- Product catalog → Product details: opens details (evidence: `website/src/app/solutions/SolutionsClient.tsx`)
- Visitor → Download center: downloads files
- Product catalog → Download center: links downloads (evidence: `website/src/app/solutions/SolutionsClient.tsx`)
- Visitor → Product quiz: takes quiz
- Visitor → Materials calculator: calculates materials
- Visitor → Build guidance: reads instructions
- Visitor → Community stories: shares stories
- Visitor → User submissions: submits ideas
- Visitor → Workshop search: searches workshops
- Workshop search → Workshop services: requests search
- Workshop services → Web search adapter: uses adapter (evidence: `website/src/lib/workshop-sources/websearch.ts`)
- Web search adapter → Firecrawl search: calls search (evidence: `website/src/lib/workshop-sources/websearch.ts`)
- Workshop services → OpenStreetMap source: may use source
- Visitor → Notify subscriptions: requests updates
- Visitor → Geocoding endpoint: geocodes location
- Download endpoint → Neon database: may read records
