# joshua00ralph/sunny-spark-builder architecture

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

- Interactive diagram: https://gitdiagram.com/joshua00ralph/sunny-spark-builder
- Repository: https://github.com/joshua00ralph/sunny-spark-builder

## Overview

AssetOctopus is a multi-tenant asset-management and administration application. Users work in a React console to manage the asset directory, imports, audits, lifecycle and reporting; the self-hosted API handles requests and persists tenant-scoped data. The repository also includes authentication/SSO, integrations and webhooks, background jobs, and platform administration. The frontend API client documents fetch-based communication with the self-hosted backend, but the sampled material does not show its exact route dispatches, so that link is marked unverified. Several capability nodes are based on the file tree rather than inspected implementations.

Main entry points: [`server/src/db.ts`](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/db.ts) (PostgreSQL), [`server/src/index.ts`](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/index.ts) (HTTP service), [`src/lib/api-client.ts`](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/lib/api-client.ts) (API client), [`server/src/routes/directory.routes.ts`](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/routes/directory.routes.ts) (Directory API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Console"]
  node_console["Application routes"]
  node_auth_ui["Sign-in<br/>[auth.tsx]"]
  node_supabase["Supabase client<br/>[client.ts]"]
  node_api_client["API client<br/>[api-client.ts]"]
  node_directory_ui["Directory screens<br/>[directory.tsx]"]
  node_audit_ui["Site-sweep audits"]
end

subgraph group_api["API and identity"]
  node_server["HTTP service<br/>[index.ts]"]
  node_auth["Authentication and SSO<br/>[index.ts]"]
end

subgraph group_assets["Asset workflows"]
  node_directory_api["Directory API"]
  node_import_api["Import API<br/>[import.routes.ts]"]
  node_import_service["Import processing<br/>[import-service.ts]"]
  node_lifecycle["Retention and recovery"]
  node_search["Asset search<br/>[search-service.ts]"]
end

subgraph group_platform["Platform capabilities"]
  node_admin["Tenant administration<br/>[admin.routes.ts]"]
  node_webhooks["Webhook delivery<br/>[engine.ts]"]
  node_jobs["Background jobs<br/>[queue.ts]"]
  node_email["Email service<br/>[email-service.ts]"]
end

subgraph group_infra["Runtime services"]
  node_database[("PostgreSQL<br/>[db.ts]")]
  node_tenancy["Tenant context<br/>[tenancy.ts]"]
  node_storage["File storage"]
end

node_user(("Console user"))
node_external_hooks(("Webhook endpoints"))

node_user -.->|"uses"| node_console
node_user -.->|"signs in"| node_auth_ui
node_auth_ui -->|"authenticates"| node_supabase
node_console -.->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_server
node_server -->|"routes requests"| node_directory_api
node_server -->|"routes requests"| node_import_api
node_server -->|"routes requests"| node_auth
node_directory_ui -.->|"loads assets"| node_api_client
node_audit_ui -.->|"loads audits"| node_api_client
node_directory_api -->|"reads and writes"| node_database
node_directory_api -->|"resolves tenant"| node_tenancy
node_import_api -->|"delegates import"| node_import_service
node_import_service -->|"persists records"| node_database
node_lifecycle -->|"manages records"| node_database
node_admin -->|"reads and writes"| node_database
node_admin -->|"resolves tenant"| node_tenancy
node_webhooks -->|"queues deliveries"| node_database
node_jobs -->|"uses storage"| node_storage
node_external_hooks -.->|"triggers delivery"| node_webhooks

click node_console "https://github.com/joshua00ralph/sunny-spark-builder/tree/main/src/routes"
click node_auth_ui "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/routes/auth.tsx"
click node_supabase "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/integrations/supabase/client.ts"
click node_api_client "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/lib/api-client.ts"
click node_directory_ui "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/routes/directory.tsx"
click node_audit_ui "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/routes/audits.site-sweeps.tsx"
click node_server "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/index.ts"
click node_auth "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/auth/index.ts"
click node_directory_api "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/routes/directory.routes.ts"
click node_import_api "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/routes/import.routes.ts"
click node_import_service "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/services/import-service.ts"
click node_lifecycle "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/routes/lifecycle.routes.ts"
click node_search "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/search/search-service.ts"
click node_admin "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/routes/admin.routes.ts"
click node_webhooks "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/webhooks/engine.ts"
click node_jobs "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/jobs/queue.ts"
click node_email "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/email/email-service.ts"
click node_database "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/db.ts"
click node_tenancy "https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/tenancy.ts"
click node_storage "https://github.com/joshua00ralph/sunny-spark-builder/tree/main/server/src/storage"

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_console,node_auth_ui,node_supabase,node_api_client,node_directory_ui,node_audit_ui,node_user toneBlue
class node_server,node_auth toneAmber
class node_directory_api,node_import_api,node_import_service,node_lifecycle,node_search,node_external_hooks toneMint
class node_admin,node_webhooks,node_jobs,node_email toneRose
class node_database,node_tenancy,node_storage toneIndigo
```

## Components

### Console

- [Application routes](https://github.com/joshua00ralph/sunny-spark-builder/tree/main/src/routes): `src/routes`
- [Sign-in](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/routes/auth.tsx): `src/routes/auth.tsx`
- [Supabase client](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/integrations/supabase/client.ts): `src/integrations/supabase/client.ts`
- [API client](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/lib/api-client.ts): `src/lib/api-client.ts`
- [Directory screens](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/routes/directory.tsx): `src/routes/directory.tsx`
- [Site-sweep audits](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/src/routes/audits.site-sweeps.tsx): `src/routes/audits.site-sweeps.tsx`

### API and identity

- [HTTP service](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/index.ts): `server/src/index.ts`
- [Authentication and SSO](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/auth/index.ts): `server/src/auth/index.ts`

### Asset workflows

- [Directory API](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/routes/directory.routes.ts): `server/src/routes/directory.routes.ts`
- [Import API](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/routes/import.routes.ts): `server/src/routes/import.routes.ts`
- [Import processing](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/services/import-service.ts): `server/src/services/import-service.ts`
- [Retention and recovery](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/routes/lifecycle.routes.ts): `server/src/routes/lifecycle.routes.ts`
- [Asset search](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/search/search-service.ts): `server/src/search/search-service.ts`

### Platform capabilities

- [Tenant administration](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/routes/admin.routes.ts): `server/src/routes/admin.routes.ts`
- [Webhook delivery](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/webhooks/engine.ts): `server/src/webhooks/engine.ts`
- [Background jobs](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/jobs/queue.ts): `server/src/jobs/queue.ts`
- [Email service](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/email/email-service.ts): `server/src/email/email-service.ts`

### Runtime services

- [PostgreSQL](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/db.ts): `server/src/db.ts`
- [Tenant context](https://github.com/joshua00ralph/sunny-spark-builder/blob/main/server/src/tenancy.ts): `server/src/tenancy.ts`
- [File storage](https://github.com/joshua00ralph/sunny-spark-builder/tree/main/server/src/storage): `server/src/storage`

### Other components

- **Console user**
- **Webhook endpoints**

## Connections

- Console user → Application routes: uses
- Console user → Sign-in: signs in
- Sign-in → Supabase client: authenticates (evidence: `src/routes/auth.tsx`)
- Application routes → API client: requests data (evidence: `src/routes/auth.tsx`)
- API client → HTTP service: calls API
- HTTP service → Directory API: routes requests (evidence: `server/src/index.ts`)
- HTTP service → Import API: routes requests (evidence: `server/src/index.ts`)
- HTTP service → Authentication and SSO: routes requests (evidence: `server/src/index.ts`)
- Directory screens → API client: loads assets
- Site-sweep audits → API client: loads audits
- Directory API → PostgreSQL: reads and writes (evidence: `server/src/routes/directory.routes.ts`)
- Directory API → Tenant context: resolves tenant (evidence: `server/src/routes/directory.routes.ts`)
- Import API → Import processing: delegates import
- Import processing → PostgreSQL: persists records (evidence: `server/src/services/import-service.ts`)
- Retention and recovery → PostgreSQL: manages records (evidence: `server/src/routes/lifecycle.routes.ts`)
- Tenant administration → PostgreSQL: reads and writes (evidence: `server/src/routes/admin.routes.ts`)
- Tenant administration → Tenant context: resolves tenant (evidence: `server/src/routes/admin.routes.ts`)
- Webhook delivery → PostgreSQL: queues deliveries (evidence: `server/src/webhooks/engine.ts`)
- Background jobs → File storage: uses storage (evidence: `server/src/jobs/queue.ts`)
- Webhook endpoints → Webhook delivery: triggers delivery
