# cs5224-group-9/thepetstop architecture

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

- Interactive diagram: https://gitdiagram.com/cs5224-group-9/thepetstop
- Repository: https://github.com/cs5224-group-9/thepetstop

## Overview

PetStop is a Singapore pet-owner web app: owners sign in, discover licensed facilities, manage pet passports and reminders, and shop across merchants with simulated checkout. The graph emphasizes the frontend-to-API workflow, separates the documented facility-ingestion stages, and includes identity, storage, and infrastructure capabilities. README descriptions cover ingestion wiring not shown in source excerpts; those relationships are documented rather than inferred from unsampled code.

Main entry points: [`backend/config/wsgi.py`](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/config/wsgi.py) (Django API), [`frontend/components/app-provider.tsx`](https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/components/app-provider.tsx) (App state), [`backend/facilities/ingestion/fetch.py`](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/fetch.py) (Registry fetch), [`backend/facilities/ingestion/recovery.py`](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/recovery.py) (Run recovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Owner web app"]
  node_web["Next.js pages<br/>[page.tsx]"]
  node_provider["App state<br/>[app-provider.tsx]"]
  node_services["API services<br/>[services.ts]"]
  node_api_client["HTTP client<br/>[client.ts]"]
  node_adapters["Response adapters<br/>[adapters.ts]"]
  node_pet_ui["Pet passports<br/>[pets.tsx]"]
  node_facility_ui["Facility discovery<br/>[directory.tsx]"]
  node_market_ui["Marketplace UI<br/>[marketplace.tsx]"]
  node_auth["Authentication<br/>[cognito.ts]"]
end

subgraph group_backend["Backend services"]
  node_django["Django API<br/>[wsgi.py]"]
  node_accounts["Accounts<br/>[views.py]"]
  node_pets["Pet profiles<br/>[views.py]"]
  node_pet_files["Pet uploads<br/>[uploads.py]"]
  node_market["Marketplace<br/>[views.py]"]
  node_checkout["Checkout<br/>[checkout.py]"]
  node_facilities["Facility directory<br/>[views.py]"]
  node_search["Location search<br/>[search_handler.py]"]
  node_onemap["OneMap client<br/>[onemap.py]"]
  node_db[("PostgreSQL<br/>[models.py]")]
  node_storage["File storage<br/>[storage.py]"]
end

subgraph group_ingestion["Facility ingestion"]
  node_handler["Lambda handlers<br/>[handlers.py]"]
  node_fetch["Registry fetch<br/>[fetch.py]"]
  node_dispatch["Queue dispatch<br/>[dispatch.py]"]
  node_geocode["Address geocoding<br/>[geocoding.py]"]
  node_finalize["Snapshot finalize<br/>[finalize.py]"]
  node_loader["Database loader<br/>[loading.py]"]
  node_recovery["Run recovery<br/>[recovery.py]"]
  node_status["Run status<br/>[status.py]"]
  node_aws_helpers["AWS helpers<br/>[aws.py]"]
end

subgraph group_platform["AWS platform"]
  node_s3[("S3 snapshots")]
  node_sqs["SQS queue"]
  node_cognito["Amazon Cognito"]
  node_infra_api["API stack<br/>[api-stack.ts]"]
end

node_owner(("Pet owner"))

node_owner -->|"uses"| node_web
node_web -->|"renders"| node_provider
node_provider -->|"authenticates"| node_auth
node_provider -->|"loads domains"| node_services
node_services -->|"requests"| node_api_client
node_services -->|"maps responses"| node_adapters
node_provider -->|"provides state"| node_pet_ui
node_provider -.->|"provides state"| node_facility_ui
node_provider -.->|"provides state"| node_market_ui
node_auth -.->|"signs in"| node_cognito
node_api_client -.->|"HTTP requests"| node_django
node_django -.->|"routes requests"| node_accounts
node_django -.->|"routes requests"| node_pets
node_django -.->|"routes requests"| node_market
node_django -.->|"routes requests"| node_facilities
node_django -.->|"persists data"| node_db
node_pets -.->|"handles uploads"| node_pet_files
node_pet_files -.->|"stores files"| node_storage
node_market -.->|"delegates checkout"| node_checkout
node_search -->|"searches addresses"| node_onemap
node_handler -->|"dispatches fetch"| node_fetch
node_handler -->|"dispatches geocoding"| node_geocode
node_handler -->|"loads events"| node_loader
node_handler -->|"dispatches recovery"| node_recovery
node_fetch -->|"dispatches batches"| node_dispatch
node_fetch -->|"reads run state"| node_status
node_geocode -->|"uses run state"| node_status
node_geocode -->|"finalizes snapshot"| node_finalize
node_loader -->|"uses run state"| node_status
node_loader -->|"writes facilities"| node_db
node_recovery -->|"checks run state"| node_status
node_recovery -->|"resumes batches"| node_dispatch
node_recovery -->|"restarts fetch"| node_fetch
node_recovery -->|"recovers snapshot"| node_finalize
node_fetch -.->|"stores manifest"| node_s3
node_fetch -.->|"sends batches"| node_sqs
node_geocode -.->|"stores results"| node_s3
node_sqs -.->|"triggers asynchronously"| node_geocode
node_s3 -.->|"triggers ready load"| node_loader
node_infra_api -.->|"deploys API"| node_django

click node_web "https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/app/page.tsx"
click node_provider "https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/components/app-provider.tsx"
click node_services "https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/lib/api/services.ts"
click node_api_client "https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/lib/api/client.ts"
click node_adapters "https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/lib/api/adapters.ts"
click node_pet_ui "https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/components/pets.tsx"
click node_facility_ui "https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/components/directory.tsx"
click node_market_ui "https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/components/marketplace.tsx"
click node_auth "https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/lib/auth/cognito.ts"
click node_django "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/config/wsgi.py"
click node_accounts "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/accounts/views.py"
click node_pets "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/pets/views.py"
click node_pet_files "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/pets/uploads.py"
click node_market "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/marketplace/views.py"
click node_checkout "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/marketplace/checkout.py"
click node_facilities "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/views.py"
click node_search "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/search_handler.py"
click node_onemap "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/onemap.py"
click node_db "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/api/models.py"
click node_storage "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/api/storage.py"
click node_handler "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/handlers.py"
click node_fetch "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/fetch.py"
click node_dispatch "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/dispatch.py"
click node_geocode "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/geocoding.py"
click node_finalize "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/finalize.py"
click node_loader "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/loading.py"
click node_recovery "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/recovery.py"
click node_status "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/status.py"
click node_aws_helpers "https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/aws.py"
click node_infra_api "https://github.com/cs5224-group-9/thepetstop/blob/main/infra/lib/api-stack.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_web,node_provider,node_services,node_api_client,node_adapters,node_pet_ui,node_facility_ui,node_market_ui,node_auth toneBlue
class node_django,node_accounts,node_pets,node_pet_files,node_market,node_checkout,node_facilities,node_search,node_onemap,node_db,node_storage toneAmber
class node_handler,node_fetch,node_dispatch,node_geocode,node_finalize,node_loader,node_recovery,node_status,node_aws_helpers toneMint
class node_s3,node_sqs,node_cognito,node_infra_api toneRose
class node_owner toneIndigo
```

## Components

### Owner web app

- [Next.js pages](https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [App state](https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/components/app-provider.tsx): `frontend/components/app-provider.tsx`
- [API services](https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/lib/api/services.ts): `frontend/lib/api/services.ts`
- [HTTP client](https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/lib/api/client.ts): `frontend/lib/api/client.ts`
- [Response adapters](https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/lib/api/adapters.ts): `frontend/lib/api/adapters.ts`
- [Pet passports](https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/components/pets.tsx): `frontend/components/pets.tsx`
- [Facility discovery](https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/components/directory.tsx): `frontend/components/directory.tsx`
- [Marketplace UI](https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/components/marketplace.tsx): `frontend/components/marketplace.tsx`
- [Authentication](https://github.com/cs5224-group-9/thepetstop/blob/main/frontend/lib/auth/cognito.ts): `frontend/lib/auth/cognito.ts`

### Backend services

- [Django API](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/config/wsgi.py): `backend/config/wsgi.py`
- [Accounts](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/accounts/views.py): `backend/accounts/views.py`
- [Pet profiles](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/pets/views.py): `backend/pets/views.py`
- [Pet uploads](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/pets/uploads.py): `backend/pets/uploads.py`
- [Marketplace](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/marketplace/views.py): `backend/marketplace/views.py`
- [Checkout](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/marketplace/checkout.py): `backend/marketplace/checkout.py`
- [Facility directory](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/views.py): `backend/facilities/views.py`
- [Location search](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/search_handler.py): `backend/facilities/search_handler.py`
- [OneMap client](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/onemap.py): `backend/facilities/onemap.py`
- [PostgreSQL](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/api/models.py): `backend/api/models.py`
- [File storage](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/api/storage.py): `backend/api/storage.py`

### Facility ingestion

- [Lambda handlers](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/handlers.py): `backend/facilities/ingestion/handlers.py`
- [Registry fetch](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/fetch.py): `backend/facilities/ingestion/fetch.py`
- [Queue dispatch](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/dispatch.py): `backend/facilities/ingestion/dispatch.py`
- [Address geocoding](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/geocoding.py): `backend/facilities/ingestion/geocoding.py`
- [Snapshot finalize](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/finalize.py): `backend/facilities/ingestion/finalize.py`
- [Database loader](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/loading.py): `backend/facilities/ingestion/loading.py`
- [Run recovery](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/recovery.py): `backend/facilities/ingestion/recovery.py`
- [Run status](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/status.py): `backend/facilities/ingestion/status.py`
- [AWS helpers](https://github.com/cs5224-group-9/thepetstop/blob/main/backend/facilities/ingestion/aws.py): `backend/facilities/ingestion/aws.py`

### AWS platform

- **S3 snapshots**
- **SQS queue**
- **Amazon Cognito**
- [API stack](https://github.com/cs5224-group-9/thepetstop/blob/main/infra/lib/api-stack.ts): `infra/lib/api-stack.ts`

### Other components

- **Pet owner**

## Connections

- Pet owner → Next.js pages: uses (evidence: `README.md`)
- Next.js pages → App state: renders
- App state → Authentication: authenticates (evidence: `frontend/components/app-provider.tsx`)
- App state → API services: loads domains (evidence: `frontend/components/app-provider.tsx`)
- API services → HTTP client: requests (evidence: `frontend/lib/api/services.ts`)
- API services → Response adapters: maps responses (evidence: `frontend/lib/api/services.ts`)
- App state → Pet passports: provides state (evidence: `frontend/components/pets.tsx`)
- App state → Facility discovery: provides state
- App state → Marketplace UI: provides state
- Authentication → Amazon Cognito: signs in
- HTTP client → Django API: HTTP requests
- Django API → Accounts: routes requests
- Django API → Pet profiles: routes requests
- Django API → Marketplace: routes requests
- Django API → Facility directory: routes requests
- Django API → PostgreSQL: persists data
- Pet profiles → Pet uploads: handles uploads
- Pet uploads → File storage: stores files
- Marketplace → Checkout: delegates checkout
- Location search → OneMap client: searches addresses (evidence: `backend/facilities/search_handler.py`)
- Lambda handlers → Registry fetch: dispatches fetch (evidence: `backend/facilities/ingestion/handlers.py`)
- Lambda handlers → Address geocoding: dispatches geocoding (evidence: `backend/facilities/ingestion/handlers.py`)
- Lambda handlers → Database loader: loads events (evidence: `backend/facilities/ingestion/handlers.py`)
- Lambda handlers → Run recovery: dispatches recovery (evidence: `backend/facilities/ingestion/handlers.py`)
- Registry fetch → Queue dispatch: dispatches batches (evidence: `backend/facilities/ingestion/fetch.py`)
- Registry fetch → Run status: reads run state (evidence: `backend/facilities/ingestion/fetch.py`)
- Address geocoding → Run status: uses run state (evidence: `backend/facilities/ingestion/geocoding.py`)
- Address geocoding → Snapshot finalize: finalizes snapshot (evidence: `backend/facilities/ingestion/geocoding.py`)
- Database loader → Run status: uses run state (evidence: `backend/facilities/ingestion/loading.py`)
- Database loader → PostgreSQL: writes facilities (evidence: `backend/facilities/ingestion/loading.py`)
- Run recovery → Run status: checks run state (evidence: `backend/facilities/ingestion/recovery.py`)
- Run recovery → Queue dispatch: resumes batches (evidence: `backend/facilities/ingestion/recovery.py`)
- Run recovery → Registry fetch: restarts fetch (evidence: `backend/facilities/ingestion/recovery.py`)
- Run recovery → Snapshot finalize: recovers snapshot (evidence: `backend/facilities/ingestion/recovery.py`)
- Registry fetch → S3 snapshots: stores manifest
- Registry fetch → SQS queue: sends batches
- Address geocoding → S3 snapshots: stores results
- SQS queue → Address geocoding: triggers asynchronously (evidence: `README.md`)
- S3 snapshots → Database loader: triggers ready load (evidence: `README.md`)
- API stack → Django API: deploys API