# shazzann/colombocosmetics architecture

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

- Interactive diagram: https://gitdiagram.com/shazzann/colombocosmetics
- Repository: https://github.com/shazzann/colombocosmetics

## Overview

#### Purpose and Entry Points
This is a full-stack order, product, dashboard, and reporting system. The TypeScript backend exposes an HTTP API; the React frontend provides authenticated operational screens for creating and managing orders, inventory/products, receipts, labels, and reports.

- Backend startup: `backend/src/index.ts`
- Frontend bootstrap and root UI: `frontend/src/main.tsx`, `frontend/src/App.tsx`
- Database schema and seed data: `backend/prisma/schema.prisma`, `backend/prisma/seed.ts`

#### Backend API Composition
The backend is organized as route modules delegating to controllers, with a shared database client and authentication middleware. API domains are authentication, products, orders, reports, and dashboard summaries.

- Route boundary: `backend/src/routes/authRoutes.ts`, `backend/src/routes/orderRoutes.ts`, `backend/src/routes/productRoutes.ts`
- Domain handlers: `backend/src/controllers/authController.ts`, `backend/src/controllers/orderController.ts`, `backend/src/controllers/dashboardController.ts`
- Reporting handlers: `backend/src/controllers/reportsController.ts`

Control flow is expected to be: HTTP request → route selection → authentication where required → controller business/query logic → Prisma persistence → JSON response.

#### Identity and Access Boundary
Authentication is centralized in backend middleware and consumed by the frontend authentication context and route guard. This separates public registration/login access from protected operational pages.

- Server enforcement: `backend/src/middleware/authMiddleware.ts`, `backend/src/controllers/authController.ts`
- Client session state: `frontend/src/context/AuthContext.tsx`
- Client navigation gate: `frontend/src/components/ProtectedRoute.tsx`
- Public identity screens: `frontend/src/pages/Login.tsx`, `frontend/src/pages/Register.tsx`

#### Persistence and Business Domains
Prisma defines the system-of-record model and is accessed through one database client. Orders and products are the principal transactional domains; dashboard and report endpoints likely derive aggregates from those records.

- Prisma model contract: `backend/prisma/schema.prisma`
- Shared DB access: `backend/src/db/client.ts`
- Product lifecycle API: `backend/src/controllers/productController.ts`, `backend/src/routes/productRoutes.ts`
- Order lifecycle API: `backend/src/controllers/orderController.ts`, `backend/src/routes/orderRoutes.ts`

The Prisma database is an external infrastructure dependency; its concrete provider and connection settings are defined by the schema/environment rather than visible in the tree.

#### Frontend Workflow and State
The frontend is a Vite React application. It uses a centralized API client, auth context, and an order-draft context to carry state across order-creation steps and downstream document views.

- HTTP integration boundary: `frontend/src/api/client.ts`
- Draft/order workflow state: `frontend/src/context/OrderDraftContext.tsx`
- Core operations screens: `frontend/src/pages/CreateOrder.tsx`, `frontend/src/pages/Orders.tsx`, `frontend/src/pages/OrderDetails.tsx`
- Order outputs: `frontend/src/pages/Receipt.tsx`, `frontend/src/pages/DeliveryLabel.tsx`

Order presentation is decomposed into reusable order card and line-item table components under `frontend/src/components/orders/`.

#### Reporting and Operational Views
Dashboard and reporting are separate read-oriented surfaces over transactional data, while Products supports catalog/inventory management.

- Dashboard endpoint/controller: `backend/src/controllers/dashboardController.ts`
- Reports endpoint/controller: `backend/src/controllers/reportsController.ts`, `backend/src/routes/reportRoutes.ts`
- Corresponding UI: `frontend/src/pages/Dashboard.tsx`, `frontend/src/pages/Reports.tsx`, `frontend/src/pages/Products.tsx`

#### Deployment and Built Artifacts
The backend has a Docker image definition and Railway deployment configuration. The frontend has Vercel configuration. Compiled backend output is committed under `backend/dist`, mirroring the TypeScript source structure.

- Backend container/deployment: `backend/Dockerfile`, `backend/railway.json`
- Frontend deployment: `frontend/vercel.json`
- Production backend entry artifact: `backend/dist/src/index.js`

Main entry points: [`frontend/src/App.tsx`](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/App.tsx) (React application), [`frontend/src/api/client.ts`](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/api/client.ts) (API client), [`backend/src/db/client.ts`](https://github.com/shazzann/colombocosmetics/blob/main/backend/src/db/client.ts) (Prisma client), [`frontend/src/pages/CreateOrder.tsx`](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/pages/CreateOrder.tsx) (Operations screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_web_app["React application<br/>Vite React UI<br/>[App.tsx]"]
  node_api_client["API client<br/>HTTP client<br/>[client.ts]"]
  node_auth_context["Auth context<br/>client session<br/>[AuthContext.tsx]"]
  node_protected_route["Protected route<br/>navigation guard<br/>[ProtectedRoute.tsx]"]
  node_order_draft["Order draft context<br/>workflow state"]
  node_operations_ui["Operations screens<br/>order and catalog UI<br/>[CreateOrder.tsx]"]
  node_order_documents["Order documents<br/>receipt and label UI<br/>[Receipt.tsx]"]
  node_analytics_ui["Dashboard and reports<br/>read UI<br/>[Dashboard.tsx]"]
end

subgraph group_backend["TypeScript backend"]
  node_api_server["HTTP API<br/>backend entrypoint<br/>[index.ts]"]
  node_api_routes["Route modules<br/>route boundary<br/>[orderRoutes.ts]"]
  node_auth_middleware["Authentication middleware<br/>access enforcement<br/>[authMiddleware.ts]"]
  node_domain_controllers["Order and product controllers<br/>transaction handlers<br/>[orderController.ts]"]
  node_auth_controller["Auth controller<br/>identity handler<br/>[authController.ts]"]
  node_analytics_controllers["Dashboard and reports controllers<br/>aggregate handlers"]
end

subgraph group_data["Data platform"]
  node_prisma_client["Prisma client<br/>data access<br/>[client.ts]"]
  node_prisma_schema["Prisma schema and seed<br/>data model<br/>[schema.prisma]"]
  node_database[("Prisma database<br/>external database")]
end

subgraph group_deploy["Deployment"]
  node_backend_deployment{{"Backend container deployment<br/>Docker and Railway"}}
  node_frontend_deployment{{"Frontend deployment<br/>Vercel<br/>[vercel.json]"}}
end

node_web_app -->|"uses"| node_auth_context
node_web_app -->|"gates private pages"| node_protected_route
node_protected_route -->|"allows authenticated access"| node_operations_ui
node_operations_ui -->|"builds orders"| node_order_draft
node_order_draft -->|"supplies output state"| node_order_documents
node_web_app -->|"renders"| node_analytics_ui
node_auth_context -->|"adds session"| node_api_client
node_operations_ui -->|"requests API"| node_api_client
node_analytics_ui -->|"queries aggregates"| node_api_client
node_api_client -->|"HTTP JSON"| node_api_server
node_api_server -->|"dispatches"| node_api_routes
node_api_routes -->|"protects private routes"| node_auth_middleware
node_api_routes -->|"auth endpoints"| node_auth_controller
node_auth_middleware -->|"authorizes"| node_domain_controllers
node_auth_middleware -->|"authorizes"| node_analytics_controllers
node_domain_controllers -->|"persists orders and products"| node_prisma_client
node_auth_controller -->|"reads identities"| node_prisma_client
node_analytics_controllers -->|"aggregates records"| node_prisma_client
node_prisma_client -->|"Prisma queries"| node_database
node_prisma_schema -.->|"defines model"| node_database
node_backend_deployment -->|"runs backend"| node_api_server
node_frontend_deployment -->|"serves frontend"| node_web_app

click node_web_app "https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/api/client.ts"
click node_auth_context "https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/context/AuthContext.tsx"
click node_protected_route "https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/components/ProtectedRoute.tsx"
click node_order_draft "https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/context/OrderDraftContext.tsx"
click node_operations_ui "https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/pages/CreateOrder.tsx"
click node_order_documents "https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/pages/Receipt.tsx"
click node_analytics_ui "https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/pages/Dashboard.tsx"
click node_api_server "https://github.com/shazzann/colombocosmetics/blob/main/backend/src/index.ts"
click node_api_routes "https://github.com/shazzann/colombocosmetics/blob/main/backend/src/routes/orderRoutes.ts"
click node_auth_middleware "https://github.com/shazzann/colombocosmetics/blob/main/backend/src/middleware/authMiddleware.ts"
click node_domain_controllers "https://github.com/shazzann/colombocosmetics/blob/main/backend/src/controllers/orderController.ts"
click node_auth_controller "https://github.com/shazzann/colombocosmetics/blob/main/backend/src/controllers/authController.ts"
click node_analytics_controllers "https://github.com/shazzann/colombocosmetics/blob/main/backend/src/controllers/dashboardController.ts"
click node_prisma_client "https://github.com/shazzann/colombocosmetics/blob/main/backend/src/db/client.ts"
click node_prisma_schema "https://github.com/shazzann/colombocosmetics/blob/main/backend/prisma/schema.prisma"
click node_backend_deployment "https://github.com/shazzann/colombocosmetics/blob/main/backend/Dockerfile"
click node_frontend_deployment "https://github.com/shazzann/colombocosmetics/blob/main/frontend/vercel.json"

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_app,node_api_client,node_auth_context,node_protected_route,node_order_draft,node_operations_ui,node_order_documents,node_analytics_ui toneBlue
class node_api_server,node_api_routes,node_auth_middleware,node_domain_controllers,node_auth_controller,node_analytics_controllers toneAmber
class node_prisma_client,node_prisma_schema,node_database toneMint
class node_backend_deployment,node_frontend_deployment toneRose
```

## Components

### React frontend

- [React application](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/App.tsx): Vite React UI · Authenticated operational application root. · `frontend/src/App.tsx`
- [API client](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/api/client.ts): HTTP client · `frontend/src/api/client.ts`
- [Auth context](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/context/AuthContext.tsx): client session · `frontend/src/context/AuthContext.tsx`
- [Protected route](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/components/ProtectedRoute.tsx): navigation guard · `frontend/src/components/ProtectedRoute.tsx`
- [Order draft context](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/context/OrderDraftContext.tsx): workflow state · Carries order state across creation steps and outputs. · `frontend/src/context/OrderDraftContext.tsx`
- [Operations screens](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/pages/CreateOrder.tsx): order and catalog UI · Create, browse, inspect orders and manage products. · `frontend/src/pages/CreateOrder.tsx`
- [Order documents](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/pages/Receipt.tsx): receipt and label UI · `frontend/src/pages/Receipt.tsx`
- [Dashboard and reports](https://github.com/shazzann/colombocosmetics/blob/main/frontend/src/pages/Dashboard.tsx): read UI · `frontend/src/pages/Dashboard.tsx`

### TypeScript backend

- [HTTP API](https://github.com/shazzann/colombocosmetics/blob/main/backend/src/index.ts): backend entrypoint · `backend/src/index.ts`
- [Route modules](https://github.com/shazzann/colombocosmetics/blob/main/backend/src/routes/orderRoutes.ts): route boundary · Auth, order, and product routes select API handlers. · `backend/src/routes/orderRoutes.ts`
- [Authentication middleware](https://github.com/shazzann/colombocosmetics/blob/main/backend/src/middleware/authMiddleware.ts): access enforcement · `backend/src/middleware/authMiddleware.ts`
- [Order and product controllers](https://github.com/shazzann/colombocosmetics/blob/main/backend/src/controllers/orderController.ts): transaction handlers · `backend/src/controllers/orderController.ts`
- [Auth controller](https://github.com/shazzann/colombocosmetics/blob/main/backend/src/controllers/authController.ts): identity handler · Handles registration and login. · `backend/src/controllers/authController.ts`
- [Dashboard and reports controllers](https://github.com/shazzann/colombocosmetics/blob/main/backend/src/controllers/dashboardController.ts): aggregate handlers · `backend/src/controllers/dashboardController.ts`

### Data platform

- [Prisma client](https://github.com/shazzann/colombocosmetics/blob/main/backend/src/db/client.ts): data access · Shared persistence client. · `backend/src/db/client.ts`
- [Prisma schema and seed](https://github.com/shazzann/colombocosmetics/blob/main/backend/prisma/schema.prisma): data model · System-of-record contract and seed data. · `backend/prisma/schema.prisma`
- **Prisma database**: external database · Provider and connection are configured outside the repository tree.

### Deployment

- [Backend container deployment](https://github.com/shazzann/colombocosmetics/blob/main/backend/Dockerfile): Docker and Railway · `backend/Dockerfile`
- [Frontend deployment](https://github.com/shazzann/colombocosmetics/blob/main/frontend/vercel.json): Vercel · `frontend/vercel.json`

## Connections

- React application → Auth context: uses
- React application → Protected route: gates private pages
- Protected route → Operations screens: allows authenticated access
- Operations screens → Order draft context: builds orders
- Order draft context → Order documents: supplies output state
- React application → Dashboard and reports: renders
- Auth context → API client: adds session
- Operations screens → API client: requests API
- Dashboard and reports → API client: queries aggregates
- API client → HTTP API: HTTP JSON
- HTTP API → Route modules: dispatches
- Route modules → Authentication middleware: protects private routes
- Route modules → Auth controller: auth endpoints
- Authentication middleware → Order and product controllers: authorizes
- Authentication middleware → Dashboard and reports controllers: authorizes
- Order and product controllers → Prisma client: persists orders and products
- Auth controller → Prisma client: reads identities
- Dashboard and reports controllers → Prisma client: aggregates records
- Prisma client → Prisma database: Prisma queries
- Prisma schema and seed → Prisma database: defines model
- Backend container deployment → HTTP API: runs backend
- Frontend deployment → React application: serves frontend