# pedrosouza458/carbojobs architecture

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

- Interactive diagram: https://gitdiagram.com/pedrosouza458/carbojobs
- Repository: https://github.com/pedrosouza458/carbojobs

## Overview

1. **Top-level shape**
   - The repository is a two-app system: `api/` for the backend and `web/` for the customer/provider-facing frontend.
   - The product domain is a local services marketplace: providers, businesses, appointments, links, referrals, and reporting.

2. **Backend boundary**
   - `api/` is a TypeScript HTTP service built around `src/http/server.ts`, `setup.ts`, and route modules under `src/http/routes/`.
   - `vercel.json` suggests the API is deployed as serverless/edge-style functions or a Vercel-hosted service, not a long-running custom server only.
   - `src/lib/db.ts` is the database access boundary; all domain data appears to flow through it.

3. **Backend subdomains**
   - The backend is organized by feature: `users`, `business`, `appointments`, `links`, `indications`, `tokens`, and `charts`.
   - `users` covers sign-up, login, profile retrieval/update, password recovery, deletion, and provider discovery.
   - `business` manages provider business profiles.
   - `appointments` manages creation, listing, status changes, and hiding.
   - `links` manages provider link records.
   - `indications` supports referral/endorsement flows.
   - `charts` exposes aggregated appointment metrics by day, month, and service.

4. **Auth and access control**
   - `api/src/http/middlewares/auth.ts` is the main security boundary for protected routes.
   - The presence of `tokens/get-token.ts` plus login/forgot-password flows indicates token-based authentication.
   - On the frontend, `web/src/auth/auth.ts` and `web/src/middleware.ts` enforce session-aware routing and protected UI access.

5. **Frontend boundary**
   - `web/` is a Next.js app router application (`src/app/`), with route groups for public auth, authenticated dashboard areas, reports, providers, schedules, and upload tooling.
   - Server actions are used heavily: many pages have colocated `action.ts` files, indicating form submissions and mutations are handled in the Next app layer rather than only through client-side fetches.
   - `web/src/http/*` contains typed API client wrappers that talk to the backend.

6. **Frontend domain views**
   - The UI is segmented by user task: sign-in/sign-up/forgot-password, profile, business, providers, schedules, appointments, links, and reports.
   - Reusable components under `web/src/components/` implement forms, tables/lists, buttons, charts, avatars, banners, and dialogs.
   - The `reports` area consumes analytics components and chart primitives, aligning with the backend’s aggregation endpoints.

7. **Primary data flows**
   - User authentication flows from the web auth pages to backend user/token routes, then into protected app sections.
   - CRUD flows for appointments, business, links, schedules, and profile updates go from Next server actions/client components to `web/src/http/*` wrappers, then to the API routes, then to the DB layer.
   - Reporting flows go from the `reports` page to chart components, backed by API aggregation endpoints for appointment metrics.

8. **Shared domain model**
   - Both apps define parallel enum sets under `src/enums/` for cities, days, hours, roles, services, and status.
   - This duplication suggests a shared contract by convention rather than a dedicated shared package, so frontend and backend must stay in sync manually.

9. **File upload integration**
   - `web/src/app/api/uploadthing` and `web/src/utils/uploadthing.ts` show an upload service integrated through Next.js route handlers.
   - This is a distinct external boundary from the main business API, likely used for media or profile assets.

10. **WhatsApp/browser session artifact**
   - `api/.wwebjs_auth/` contains a persisted browser session for WhatsApp Web automation.
   - That strongly suggests the backend also maintains a WhatsApp-based integration, probably for messaging or notifications, and that integration depends on browser session state stored on disk.

11. **Seeding and runtime setup**
   - `api/src/http/seed.ts` indicates the backend can initialize reference data.
   - `api/src/http/setup.ts` and `web/src/lib/utils.ts`/utility modules suggest both apps have a fair amount of shared platform glue around configuration, formatting, and request handling.

12. **Architecture summary for diagramming**
   - Draw this as a two-tier system: a Next.js frontend with app-router pages/actions and a Fastify-like API backend with feature-based routes and middleware, both centered on the same business domain.
   - Add two external branches: a database behind `api/src/lib/db.ts`, and a WhatsApp Web session-backed automation layer inside the API.
   - The reports/charts path is the clearest read-only analytics pipeline; the auth/users/appointments/business/links paths are the primary transactional pipelines.

Main entry points: [`api/src/http/server.ts`](https://github.com/pedrosouza458/carbojobs/blob/main/api/src/http/server.ts) (HTTP server), [`web/src/app`](https://github.com/pedrosouza458/carbojobs/tree/main/web/src/app) (Next app), [`api/src/lib/db.ts`](https://github.com/pedrosouza458/carbojobs/blob/main/api/src/lib/db.ts) (Database), [`web/src/auth/auth.ts`](https://github.com/pedrosouza458/carbojobs/blob/main/web/src/auth/auth.ts) (Auth layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_api_server["HTTP server<br/>API entrypoint<br/>[server.ts]"]
  node_api_setup["Setup<br/>API config<br/>[setup.ts]"]
  node_api_auth_mw["Auth guard<br/>middleware<br/>[auth.ts]"]
  node_api_users["Users<br/>route area"]
  node_api_business["Business<br/>route area"]
  node_api_appointments["Appointments<br/>route area"]
  node_api_links["Links<br/>route area"]
  node_api_indications["Indications<br/>route area"]
  node_api_tokens["Tokens<br/>route area"]
  node_api_charts["Charts<br/>route area"]
  node_api_seed["Seed<br/>runtime task<br/>[seed.ts]"]
end

subgraph group_web["Web"]
  node_web_app["Next app<br/>frontend app"]
  node_web_auth["Auth layer<br/>[auth.ts]"]
  node_web_middleware["Middleware<br/>routing guard<br/>[middleware.ts]"]
  node_web_http["API client<br/>frontend http"]
  node_web_actions["Server actions<br/>mutation layer"]
  node_web_ui["UI system<br/>components"]
  node_web_upload["Uploadthing<br/>upload integration"]
  node_shared_enums["Enums<br/>shared contract"]
end

subgraph group_external["External"]
  node_api_db[("Database<br/>data access<br/>[db.ts]")]
  node_api_wa[("WhatsApp session<br/>integration state<br/>[session]")]
end

node_api_server -->|"uses"| node_api_setup
node_api_server -->|"protects"| node_api_auth_mw
node_api_server -->|"registers"| node_api_users
node_api_server -->|"registers"| node_api_business
node_api_server -->|"registers"| node_api_appointments
node_api_server -->|"registers"| node_api_links
node_api_server -->|"registers"| node_api_indications
node_api_server -->|"registers"| node_api_tokens
node_api_server -->|"registers"| node_api_charts
node_api_users -->|"reads/writes"| node_api_db
node_api_business -->|"reads/writes"| node_api_db
node_api_appointments -->|"reads/writes"| node_api_db
node_api_links -->|"reads/writes"| node_api_db
node_api_indications -->|"reads/writes"| node_api_db
node_api_tokens -->|"reads/writes"| node_api_db
node_api_charts -->|"aggregates"| node_api_db
node_api_seed -->|"initializes"| node_api_db
node_api_wa -.->|"supports"| node_api_server
node_web_app -->|"uses"| node_web_auth
node_web_app -->|"guards"| node_web_middleware
node_web_app -->|"invokes"| node_web_actions
node_web_app -->|"fetches"| node_web_http
node_web_app -->|"renders"| node_web_ui
node_web_app -->|"uploads"| node_web_upload
node_web_app -.->|"shares model"| node_shared_enums
node_web_http -->|"calls"| node_api_server
node_web_actions -->|"delegates"| node_web_http
node_web_auth -->|"authenticates"| node_api_tokens
node_web_auth -->|"authenticates"| node_api_users
node_web_ui -->|"visualizes"| node_api_charts

click node_api_server "https://github.com/pedrosouza458/carbojobs/blob/main/api/src/http/server.ts"
click node_api_setup "https://github.com/pedrosouza458/carbojobs/blob/main/api/src/http/setup.ts"
click node_api_auth_mw "https://github.com/pedrosouza458/carbojobs/blob/main/api/src/http/middlewares/auth.ts"
click node_api_users "https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/users"
click node_api_business "https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/business"
click node_api_appointments "https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/appointments"
click node_api_links "https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/links"
click node_api_indications "https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/indications"
click node_api_tokens "https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/tokens"
click node_api_charts "https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/(charts)/appointments"
click node_api_seed "https://github.com/pedrosouza458/carbojobs/blob/main/api/src/http/seed.ts"
click node_api_db "https://github.com/pedrosouza458/carbojobs/blob/main/api/src/lib/db.ts"
click node_api_wa "https://github.com/pedrosouza458/carbojobs/blob/main/api/.wwebjs_auth/session"
click node_web_app "https://github.com/pedrosouza458/carbojobs/tree/main/web/src/app"
click node_web_auth "https://github.com/pedrosouza458/carbojobs/blob/main/web/src/auth/auth.ts"
click node_web_middleware "https://github.com/pedrosouza458/carbojobs/blob/main/web/src/middleware.ts"
click node_web_http "https://github.com/pedrosouza458/carbojobs/tree/main/web/src/http"
click node_web_ui "https://github.com/pedrosouza458/carbojobs/tree/main/web/src/components"
click node_web_upload "https://github.com/pedrosouza458/carbojobs/tree/main/web/src/app/api/uploadthing"
click node_shared_enums "https://github.com/pedrosouza458/carbojobs/tree/main/web/src/enums"

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_api_server,node_api_setup,node_api_auth_mw,node_api_users,node_api_business,node_api_appointments,node_api_links,node_api_indications,node_api_tokens,node_api_charts,node_api_seed toneBlue
class node_web_app,node_web_auth,node_web_middleware,node_web_http,node_web_actions,node_web_ui,node_web_upload,node_shared_enums toneAmber
class node_api_db,node_api_wa toneMint
```

## Components

### API

TypeScript backend service and domain routes

- [HTTP server](https://github.com/pedrosouza458/carbojobs/blob/main/api/src/http/server.ts): API entrypoint · Bootstraps the backend HTTP service · `api/src/http/server.ts`
- [Setup](https://github.com/pedrosouza458/carbojobs/blob/main/api/src/http/setup.ts): API config · Wires server configuration and runtime setup · `api/src/http/setup.ts`
- [Auth guard](https://github.com/pedrosouza458/carbojobs/blob/main/api/src/http/middlewares/auth.ts): middleware · Protects authenticated backend routes · `api/src/http/middlewares/auth.ts`
- [Users](https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/users): route area · Sign-up, login, profile, password recovery, provider discovery · `api/src/http/routes/users`
- [Business](https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/business): route area · Provider business profile management · `api/src/http/routes/business`
- [Appointments](https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/appointments): route area · Appointment creation, listing, status, and hiding · `api/src/http/routes/appointments`
- [Links](https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/links): route area · Provider link record management · `api/src/http/routes/links`
- [Indications](https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/indications): route area · Referral and endorsement flow · `api/src/http/routes/indications`
- [Tokens](https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/tokens): route area · Token issuance for auth flows · `api/src/http/routes/tokens`
- [Charts](https://github.com/pedrosouza458/carbojobs/tree/main/api/src/http/routes/(charts)/appointments): route area · Appointment analytics aggregation endpoints · `api/src/http/routes/(charts)/appointments`
- [Seed](https://github.com/pedrosouza458/carbojobs/blob/main/api/src/http/seed.ts): runtime task · Initial reference data setup · `api/src/http/seed.ts`

### Web

Next.js frontend and UI layer

- [Next app](https://github.com/pedrosouza458/carbojobs/tree/main/web/src/app): frontend app · App-router frontend for public and authenticated flows · `web/src/app`
- [Auth layer](https://github.com/pedrosouza458/carbojobs/blob/main/web/src/auth/auth.ts): auth · Session-aware routing and protected UI access · `web/src/auth/auth.ts`
- [Middleware](https://github.com/pedrosouza458/carbojobs/blob/main/web/src/middleware.ts): routing guard · Frontend route protection and session handling · `web/src/middleware.ts`
- [API client](https://github.com/pedrosouza458/carbojobs/tree/main/web/src/http): frontend http · Typed wrappers for backend requests · `web/src/http`
- **Server actions**: mutation layer · Colocated form submissions and state-changing actions
- [UI system](https://github.com/pedrosouza458/carbojobs/tree/main/web/src/components): components · Reusable forms, lists, charts, dialogs, and primitives · `web/src/components`
- [Uploadthing](https://github.com/pedrosouza458/carbojobs/tree/main/web/src/app/api/uploadthing): upload integration · Next route handlers for file upload service integration · `web/src/app/api/uploadthing`
- [Enums](https://github.com/pedrosouza458/carbojobs/tree/main/web/src/enums): shared contract · Parallel domain enums kept in sync across apps · `web/src/enums`

### External

Storage and integration boundaries

- [Database](https://github.com/pedrosouza458/carbojobs/blob/main/api/src/lib/db.ts): data access · Primary persistence boundary for domain data · `api/src/lib/db.ts`
- [WhatsApp session](https://github.com/pedrosouza458/carbojobs/blob/main/api/.wwebjs_auth/session): integration state · Persisted browser session for WhatsApp Web automation · `api/.wwebjs_auth/session`

## Connections

- HTTP server → Setup: uses · Server bootstrap relies on setup wiring
- HTTP server → Auth guard: protects · Routes flow through auth middleware
- HTTP server → Users: registers · HTTP server mounts feature routes
- HTTP server → Business: registers · HTTP server mounts feature routes
- HTTP server → Appointments: registers · HTTP server mounts feature routes
- HTTP server → Links: registers · HTTP server mounts feature routes
- HTTP server → Indications: registers · HTTP server mounts feature routes
- HTTP server → Tokens: registers · HTTP server mounts feature routes
- HTTP server → Charts: registers · HTTP server mounts feature routes
- Users → Database: reads/writes · User records and auth data persist through the DB boundary
- Business → Database: reads/writes · Business profile operations persist through the DB boundary
- Appointments → Database: reads/writes · Appointment operations persist through the DB boundary
- Links → Database: reads/writes · Link records persist through the DB boundary
- Indications → Database: reads/writes · Referral flow data persists through the DB boundary
- Tokens → Database: reads/writes · Token lookup/issuance depends on stored data
- Charts → Database: aggregates · Reporting endpoints compute metrics from persisted appointments
- Seed → Database: initializes · Seed task populates reference data
- WhatsApp session → HTTP server: supports · WhatsApp automation is an adjacent backend integration
- Next app → Auth layer: uses · Pages depend on auth/session helpers
- Next app → Middleware: guards · Frontend routing is protected by middleware
- Next app → Server actions: invokes · Pages submit mutations through server actions
- Next app → API client: fetches · UI calls backend through typed client wrappers
- Next app → UI system: renders · Pages are assembled from reusable components
- Next app → Uploadthing: uploads · App integrates file upload route handlers
- Next app → Enums: shares model · Frontend mirrors backend domain enums
- API client → HTTP server: calls · Client wrappers target the backend API
- Server actions → API client: delegates · Server actions reuse typed HTTP helpers
- Auth layer → Tokens: authenticates · Session-aware flows depend on backend token endpoints
- Auth layer → Users: authenticates · Login, signup, and profile flows go through user routes
- UI system → Charts: visualizes · Analytics UI consumes aggregated chart data
