How pedrosouza458/carbojobs works
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: server.ts HTTP server · app Next app · db.ts Database · auth.ts Auth layer
Components 21
API
TypeScript backend service and domain routes
- HTTP server · Bootstraps the backend HTTP service
api/src/http/server.ts - Setup · Wires server configuration and runtime setup
api/src/http/setup.ts - Auth guard · Protects authenticated backend routes
api/src/http/middlewares/auth.ts - Users · Sign-up, login, profile, password recovery, provider discovery
api/src/http/routes/users - Business · Provider business profile management
api/src/http/routes/business - Appointments · Appointment creation, listing, status, and hiding
api/src/http/routes/appointments - Links · Provider link record management
api/src/http/routes/links - Indications · Referral and endorsement flow
api/src/http/routes/indications - Tokens · Token issuance for auth flows
api/src/http/routes/tokens - Charts · Appointment analytics aggregation endpoints
api/src/http/routes/(charts)/appointments - Seed · Initial reference data setup
api/src/http/seed.ts
Web
Next.js frontend and UI layer
- Next app · App-router frontend for public and authenticated flows
web/src/app - Auth layer · Session-aware routing and protected UI access
web/src/auth/auth.ts - Middleware · Frontend route protection and session handling
web/src/middleware.ts - API client · Typed wrappers for backend requests
web/src/http - Server actions · Colocated form submissions and state-changing actions
- UI system · Reusable forms, lists, charts, dialogs, and primitives
web/src/components - Uploadthing · Next route handlers for file upload service integration
web/src/app/api/uploadthing - Enums · Parallel domain enums kept in sync across apps
web/src/enums
External
Storage and integration boundaries
- Database · Primary persistence boundary for domain data
api/src/lib/db.ts - WhatsApp session · Persisted browser session for WhatsApp Web automation
api/.wwebjs_auth/session
Connections 30
- 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