# skycinema-dmani/skycirrus architecture

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

- Interactive diagram: https://gitdiagram.com/skycinema-dmani/skycirrus
- Repository: https://github.com/skycinema-dmani/skycirrus

## Overview

#### Purpose and Top-Level Shape
This is a pnpm workspace with a TypeScript React/Vite client and a Node.js API server. It appears to support a branded product/services/projects website plus a protected admin area for managing business content and appointments. Primary runtime entry points are `client/src/main.tsx` and `server/src/index.ts`.

#### Client Application Shell
The browser application is bootstrapped by `client/src/main.tsx`, with `client/src/App.tsx` acting as the application composition/routing root. Shared site chrome is centralized in `client/src/components/layout/Layout.tsx`, `client/src/components/layout/Header.tsx`, and `client/src/components/layout/Footer.tsx`; public pages should pass through this boundary rather than independently recreating navigation or footer behavior.

#### Public Content Pages
Page-level feature boundaries are in `client/src/pages/`, including catalog, detail, and informational views: `ProductsPage.tsx`, `ProductDetailPage.tsx`, `ProjectsPage.tsx`, `ProjectDetailPage.tsx`, `ServicesPage.tsx`, and `ServiceDetailPage.tsx`. The home experience is assembled from independently reusable sections under `client/src/components/home/`, notably `HeroSection.tsx`, `FeaturedProductsSection.tsx`, and `ProjectsSection.tsx`. This separates route orchestration from homepage content blocks.

#### Client Data and Domain Boundary
Client-side API access is intended to flow through `client/src/lib/api.ts`; shared domain contracts live in `client/src/types/index.ts`. `client/src/lib/mockData.ts` suggests the UI can be populated without the backend, while `client/src/lib/constants.ts` centralizes static application values. Components and pages should consume typed data through this layer rather than binding directly to server response shapes.

#### Admin Surface and Authentication
Administrative routes are isolated under `client/src/pages/admin/`, with entry/login and operational areas in `AdminLogin.tsx`, `AdminDashboard.tsx`, `AdminProducts.tsx`, `AdminProjects.tsx`, and `AdminAppointments.tsx`. This represents a distinct control plane from public browsing and depends on the server authentication boundary in `server/src/routes/auth.ts` and `server/src/middleware/auth.ts`.

#### API Server and Content Resources
The Express-style server starts from `server/src/index.ts`. Route modules expose major resource boundaries: authentication in `server/src/routes/auth.ts`, product/catalog operations in `server/src/routes/products.ts`, category operations in `server/src/routes/categories.ts`, and additional business resources through `server/src/routes/extended.ts`. Route handlers should use shared output and transformation conventions from `server/src/utils/response.ts` and `server/src/utils/mappers.ts`.

#### Persistence, Environment, and Request Middleware
Database setup is encapsulated in `server/src/config/db.ts`; environment loading/validation belongs in `server/src/config/env.ts`, with expected deployment variables documented by `server/.env.example`. Cross-cutting server controls are middleware: authorization in `server/src/middleware/auth.ts`, centralized failures in `server/src/middleware/errorHandler.ts`, and asset/form upload handling in `server/src/middleware/upload.ts`. The database initialization path is `server/scripts/setup-db.js`.

#### Runtime and Delivery Boundaries
The client is a Vite-built React application configured by `client/vite.config.ts`, styled through Tailwind/PostCSS configuration and `client/src/index.css`. The server is an independently packaged Node TypeScript service (`server/package.json`), and workspace orchestration is defined by `pnpm-workspace.yaml`. External infrastructure is implied primarily by the configured database and environment-driven service settings; no specific hosted provider is identifiable from the supplied tree.

Main entry points: [`server/src/index.ts`](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/index.ts) (Server entry), [`client/src/App.tsx`](https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/App.tsx) (App and routing), [`client/src/lib/api.ts`](https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/lib/api.ts) (Client API boundary), [`server/src/routes/products.ts`](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/routes/products.ts) (Catalog routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_client_main(("Client bootstrap<br/>React entry<br/>[main.tsx]"))
  node_client_app["App and routing<br/>route root<br/>[App.tsx]"]
  node_layout["Shared site layout<br/>UI shell<br/>[Layout.tsx]"]
  node_public_pages["Public catalog pages<br/>page routes"]
  node_home_sections["Home sections<br/>reusable UI<br/>[HeroSection.tsx]"]
  node_client_api["Client API boundary<br/>API client<br/>[api.ts]"]
  node_contracts["Domain contracts<br/>TypeScript types<br/>[index.ts]"]
  node_mock_data["Mock data<br/>local data source<br/>[mockData.ts]"]
end

subgraph group_admin["Admin Control Plane"]
  node_admin_routes["Admin routes<br/>protected pages<br/>[AdminDashboard.tsx]"]
end

subgraph group_server["Node API Server"]
  node_server_entry(("Server entry<br/>Node entry<br/>[index.ts]"))
  node_auth_routes["Authentication routes<br/>API routes<br/>[auth.ts]"]
  node_resource_routes["Catalog routes<br/>API routes<br/>[products.ts]"]
  node_extended_routes["Business resource routes<br/>API routes<br/>[extended.ts]"]
  node_auth_middleware["Authorization middleware<br/>request middleware<br/>[auth.ts]"]
  node_request_middleware["Request safeguards<br/>request middleware<br/>[errorHandler.ts]"]
  node_response_utils["Response mapping<br/>server utilities<br/>[response.ts]"]
  node_environment["Environment configuration<br/>runtime configuration<br/>[env.ts]"]
  node_database[("Database<br/>persistence<br/>[db.ts]")]
end

node_workspace{{"pnpm workspace<br/>build orchestration"}}

node_workspace -->|"runs"| node_client_main
node_workspace -->|"runs"| node_server_entry
node_client_main -->|"mounts"| node_client_app
node_client_app -->|"wraps public routes"| node_layout
node_client_app -->|"routes to"| node_public_pages
node_client_app -->|"composes home"| node_home_sections
node_client_app -->|"routes to"| node_admin_routes
node_public_pages -->|"loads data through"| node_client_api
node_home_sections -->|"loads data through"| node_client_api
node_public_pages -.->|"can use"| node_mock_data
node_client_api -->|"uses"| node_contracts
node_admin_routes -->|"authenticates and manages via"| node_client_api
node_client_api -->|"HTTP requests"| node_server_entry
node_server_entry -->|"registers"| node_auth_routes
node_server_entry -->|"registers"| node_resource_routes
node_server_entry -->|"registers"| node_extended_routes
node_server_entry -->|"applies"| node_request_middleware
node_auth_routes -->|"establishes access control"| node_auth_middleware
node_resource_routes -.->|"protects writes"| node_auth_middleware
node_extended_routes -->|"protects admin operations"| node_auth_middleware
node_auth_routes -->|"formats responses"| node_response_utils
node_resource_routes -->|"maps responses"| node_response_utils
node_extended_routes -->|"maps responses"| node_response_utils
node_resource_routes -->|"reads and writes"| node_database
node_extended_routes -->|"reads and writes"| node_database
node_server_entry -->|"loads"| node_environment
node_environment -->|"supplies connection settings"| node_database

click node_client_main "https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/main.tsx"
click node_client_app "https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/App.tsx"
click node_layout "https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/components/layout/Layout.tsx"
click node_home_sections "https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/components/home/HeroSection.tsx"
click node_client_api "https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/lib/api.ts"
click node_contracts "https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/types/index.ts"
click node_mock_data "https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/lib/mockData.ts"
click node_admin_routes "https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/pages/admin/AdminDashboard.tsx"
click node_server_entry "https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/index.ts"
click node_auth_routes "https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/routes/auth.ts"
click node_resource_routes "https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/routes/products.ts"
click node_extended_routes "https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/routes/extended.ts"
click node_auth_middleware "https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/middleware/auth.ts"
click node_request_middleware "https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/middleware/errorHandler.ts"
click node_response_utils "https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/utils/response.ts"
click node_environment "https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/config/env.ts"
click node_database "https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/config/db.ts"
click node_workspace "https://github.com/skycinema-dmani/skycirrus/blob/main/pnpm-workspace.yaml"

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_client_main,node_client_app,node_layout,node_public_pages,node_home_sections,node_client_api,node_contracts,node_mock_data toneBlue
class node_admin_routes toneAmber
class node_server_entry,node_auth_routes,node_resource_routes,node_extended_routes,node_auth_middleware,node_request_middleware,node_response_utils,node_environment,node_database toneMint
class node_workspace toneNeutral
```

## Components

### React Client

Vite browser application.

- [Client bootstrap](https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/main.tsx): React entry · `client/src/main.tsx`
- [App and routing](https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/App.tsx): route root · `client/src/App.tsx`
- [Shared site layout](https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/components/layout/Layout.tsx): UI shell · Owns shared header and footer chrome. · `client/src/components/layout/Layout.tsx`
- **Public catalog pages**: page routes · Products, projects, and services listing/detail views.
- [Home sections](https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/components/home/HeroSection.tsx): reusable UI · Hero, featured products, and projects sections. · `client/src/components/home/HeroSection.tsx`
- [Client API boundary](https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/lib/api.ts): API client · `client/src/lib/api.ts`
- [Domain contracts](https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/types/index.ts): TypeScript types · `client/src/types/index.ts`
- [Mock data](https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/lib/mockData.ts): local data source · Supports UI population without the API. · `client/src/lib/mockData.ts`

### Admin Control Plane

Protected content and appointment management.

- [Admin routes](https://github.com/skycinema-dmani/skycirrus/blob/main/client/src/pages/admin/AdminDashboard.tsx): protected pages · Login, dashboard, products, projects, and appointments. · `client/src/pages/admin/AdminDashboard.tsx`

### Node API Server

Express-style API service.

- [Server entry](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/index.ts): Node entry · `server/src/index.ts`
- [Authentication routes](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/routes/auth.ts): API routes · `server/src/routes/auth.ts`
- [Catalog routes](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/routes/products.ts): API routes · Product and category resource endpoints. · `server/src/routes/products.ts`
- [Business resource routes](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/routes/extended.ts): API routes · Additional business resources such as projects and appointments. · `server/src/routes/extended.ts`
- [Authorization middleware](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/middleware/auth.ts): request middleware · `server/src/middleware/auth.ts`
- [Request safeguards](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/middleware/errorHandler.ts): request middleware · Central error handling and upload processing. · `server/src/middleware/errorHandler.ts`
- [Response mapping](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/utils/response.ts): server utilities · Shared response and domain transformation conventions. · `server/src/utils/response.ts`
- [Environment configuration](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/config/env.ts): runtime configuration · `server/src/config/env.ts`
- [Database](https://github.com/skycinema-dmani/skycirrus/blob/main/server/src/config/db.ts): persistence · Connection setup and initialized schema. · `server/src/config/db.ts`

### Other components

- [pnpm workspace](https://github.com/skycinema-dmani/skycirrus/blob/main/pnpm-workspace.yaml): build orchestration · Coordinates client and server packages. · `pnpm-workspace.yaml`

## Connections

- pnpm workspace → Client bootstrap: runs
- pnpm workspace → Server entry: runs
- Client bootstrap → App and routing: mounts
- App and routing → Shared site layout: wraps public routes
- App and routing → Public catalog pages: routes to
- App and routing → Home sections: composes home
- App and routing → Admin routes: routes to
- Public catalog pages → Client API boundary: loads data through
- Home sections → Client API boundary: loads data through
- Public catalog pages → Mock data: can use
- Client API boundary → Domain contracts: uses
- Admin routes → Client API boundary: authenticates and manages via
- Client API boundary → Server entry: HTTP requests
- Server entry → Authentication routes: registers
- Server entry → Catalog routes: registers
- Server entry → Business resource routes: registers
- Server entry → Request safeguards: applies
- Authentication routes → Authorization middleware: establishes access control
- Catalog routes → Authorization middleware: protects writes
- Business resource routes → Authorization middleware: protects admin operations
- Authentication routes → Response mapping: formats responses
- Catalog routes → Response mapping: maps responses
- Business resource routes → Response mapping: maps responses
- Catalog routes → Database: reads and writes
- Business resource routes → Database: reads and writes
- Server entry → Environment configuration: loads
- Environment configuration → Database: supplies connection settings