# hudson-f-lima/hopeos-v1 architecture

> Architecture diagram of the GitHub repository hudson-f-lima/hopeos-v1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hudson-f-lima/hopeos-v1
- Repository: https://github.com/hudson-f-lima/hopeos-v1

## Overview

KortexOS is a beauty-business operations system: staff use its web app to manage appointments and checkout, while the backend exposes authenticated and public booking APIs and persists tenant data. The main operational flow is agenda interaction through shared client state and API calls into backend routes, with scheduling engines supporting availability and Supabase-backed persistence. The README also identifies dashboard and connected records as product capabilities. Several route and UI implementations were not sampled, so those subsystems are shown without speculative internal call chains.

Main entry points: [`backend/src/app.js`](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/app.js) (HTTP application), [`js/app.js`](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/app.js) (Operations UI), [`js/ui/agenda.js`](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/agenda.js) (Agenda UI), [`js/api.js`](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_webapp["Operations UI<br/>[app.js]"]
  node_agenda_ui["Agenda UI<br/>[agenda.js]"]
  node_block_ui["Schedule blocks<br/>[agendaBloqueio.js]"]
  node_service_ui["Appointment service<br/>[atendimento.js]"]
  node_checkout_ui["Checkout UI<br/>[checkout.js]"]
  node_series_ui["Recurring series<br/>[series.js]"]
  node_dashboard_ui["Dashboard UI<br/>[dashboard.js]"]
  node_state["Client state<br/>[state.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_auth_storage["Auth storage<br/>[auth-storage.js]"]
end

subgraph group_api["Backend API"]
  node_app_server["HTTP application<br/>[app.js]"]
  node_auth_middleware["Auth middleware<br/>[auth.js]"]
  node_auth_routes["Session routes<br/>[auth.js]"]
  node_booking_routes["Public booking<br/>[publicBooking.js]"]
  node_availability_routes["Availability API<br/>[disponibilidade.js]"]
  node_agenda_routes["Operational routes<br/>[index.js]"]
end

subgraph group_domain["Operations domain"]
  node_booking_engine["Appointment handling"]
  node_availability_engine["Availability rules"]
  node_slot_engine["Slot suggestions<br/>[SlotEngine.js]"]
  node_schedule_engine["Schedule rules<br/>[ScheduleEngine.js]"]
end

subgraph group_persistence["Identity and data"]
  node_identity["Identity provider<br/>[provider.js]"]
  node_identity_store[("Identity store<br/>[identityStore.js]")]
  node_repository["Tenant repository"]
  node_supabase[("Supabase database<br/>[supabaseClient.js]")]
end

node_staff(("Staff user"))
node_external_booking_user(("Online customer"))

node_staff -->|"uses"| node_webapp
node_webapp -->|"renders"| node_agenda_ui
node_webapp -->|"renders"| node_checkout_ui
node_webapp -->|"renders"| node_series_ui
node_webapp -->|"renders"| node_dashboard_ui
node_agenda_ui -->|"requests"| node_api_client
node_agenda_ui -->|"reads and updates"| node_state
node_agenda_ui -->|"uses"| node_block_ui
node_agenda_ui -->|"uses"| node_service_ui
node_checkout_ui -->|"requests"| node_api_client
node_series_ui -->|"requests"| node_api_client
node_state -->|"loads data"| node_api_client
node_api_client -->|"reads session"| node_auth_storage
node_app_server -->|"mounts"| node_booking_routes
node_app_server -->|"mounts"| node_auth_routes
node_app_server -->|"requires authentication"| node_auth_middleware
node_app_server -->|"mounts"| node_availability_routes
node_app_server -->|"mounts"| node_agenda_routes
node_auth_middleware -->|"authenticates with"| node_identity
node_auth_middleware -->|"looks up identity"| node_identity_store
node_auth_routes -->|"uses"| node_auth_middleware
node_auth_routes -->|"uses"| node_repository
node_availability_engine -->|"uses"| node_schedule_engine
node_slot_engine -->|"uses"| node_schedule_engine
node_slot_engine -->|"computes from"| node_availability_engine
node_booking_engine -->|"uses"| node_schedule_engine
node_booking_engine -->|"uses"| node_slot_engine
node_repository -->|"queries"| node_supabase
node_external_booking_user -->|"books online"| node_booking_routes

click node_webapp "https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/app.js"
click node_agenda_ui "https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/agenda.js"
click node_block_ui "https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/agendaBloqueio.js"
click node_service_ui "https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/atendimento.js"
click node_checkout_ui "https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/checkout.js"
click node_series_ui "https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/series.js"
click node_dashboard_ui "https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/dashboard.js"
click node_state "https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/state.js"
click node_api_client "https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/api.js"
click node_auth_storage "https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/auth-storage.js"
click node_app_server "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/app.js"
click node_auth_middleware "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/middleware/auth.js"
click node_auth_routes "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/routes/auth.js"
click node_booking_routes "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/routes/publicBooking.js"
click node_availability_routes "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/routes/disponibilidade.js"
click node_agenda_routes "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/routes/index.js"
click node_booking_engine "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/engines/AtendimentoEngine.js"
click node_availability_engine "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/engines/DisponibilidadeEngine.js"
click node_slot_engine "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/engines/SlotEngine.js"
click node_schedule_engine "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/engines/ScheduleEngine.js"
click node_identity "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/auth/provider.js"
click node_identity_store "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/auth/identityStore.js"
click node_repository "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/repositories/SupabaseRepository.js"
click node_supabase "https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/db/supabaseClient.js"

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_webapp,node_agenda_ui,node_block_ui,node_service_ui,node_checkout_ui,node_series_ui,node_dashboard_ui,node_state,node_api_client,node_auth_storage,node_staff toneBlue
class node_app_server,node_auth_middleware,node_auth_routes,node_booking_routes,node_availability_routes,node_agenda_routes toneAmber
class node_booking_engine,node_availability_engine,node_slot_engine,node_schedule_engine toneMint
class node_identity,node_identity_store,node_repository,node_supabase toneRose
class node_external_booking_user toneIndigo
```

## Components

### Web application

- [Operations UI](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/app.js): `js/app.js`
- [Agenda UI](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/agenda.js): `js/ui/agenda.js`
- [Schedule blocks](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/agendaBloqueio.js): `js/ui/agendaBloqueio.js`
- [Appointment service](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/atendimento.js): `js/ui/atendimento.js`
- [Checkout UI](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/checkout.js): `js/ui/checkout.js`
- [Recurring series](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/series.js): `js/ui/series.js`
- [Dashboard UI](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/ui/dashboard.js): `js/ui/dashboard.js`
- [Client state](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/state.js): `js/state.js`
- [API client](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/api.js): `js/api.js`
- [Auth storage](https://github.com/hudson-f-lima/hopeos-v1/blob/main/js/auth-storage.js): `js/auth-storage.js`

### Backend API

- [HTTP application](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/app.js): `backend/src/app.js`
- [Auth middleware](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/middleware/auth.js): `backend/src/middleware/auth.js`
- [Session routes](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/routes/auth.js): `backend/src/routes/auth.js`
- [Public booking](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/routes/publicBooking.js): `backend/src/routes/publicBooking.js`
- [Availability API](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/routes/disponibilidade.js): `backend/src/routes/disponibilidade.js`
- [Operational routes](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/routes/index.js): `backend/src/routes/index.js`

### Operations domain

- [Appointment handling](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/engines/AtendimentoEngine.js): `backend/src/engines/AtendimentoEngine.js`
- [Availability rules](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/engines/DisponibilidadeEngine.js): `backend/src/engines/DisponibilidadeEngine.js`
- [Slot suggestions](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/engines/SlotEngine.js): `backend/src/engines/SlotEngine.js`
- [Schedule rules](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/engines/ScheduleEngine.js): `backend/src/engines/ScheduleEngine.js`

### Identity and data

- [Identity provider](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/auth/provider.js): `backend/src/auth/provider.js`
- [Identity store](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/auth/identityStore.js): `backend/src/auth/identityStore.js`
- [Tenant repository](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/repositories/SupabaseRepository.js): `backend/src/repositories/SupabaseRepository.js`
- [Supabase database](https://github.com/hudson-f-lima/hopeos-v1/blob/main/backend/src/db/supabaseClient.js): `backend/src/db/supabaseClient.js`

### Other components

- **Staff user**
- **Online customer**

## Connections

- Staff user → Operations UI: uses (evidence: `README.md`)
- Operations UI → Agenda UI: renders (evidence: `js/app.js`)
- Operations UI → Checkout UI: renders (evidence: `js/app.js`)
- Operations UI → Recurring series: renders (evidence: `js/app.js`)
- Operations UI → Dashboard UI: renders (evidence: `js/app.js`)
- Agenda UI → API client: requests (evidence: `js/ui/agenda.js`)
- Agenda UI → Client state: reads and updates (evidence: `js/ui/agenda.js`)
- Agenda UI → Schedule blocks: uses (evidence: `js/ui/agenda.js`)
- Agenda UI → Appointment service: uses (evidence: `js/ui/agenda.js`)
- Checkout UI → API client: requests (evidence: `js/ui/checkout.js`)
- Recurring series → API client: requests (evidence: `js/ui/series.js`)
- Client state → API client: loads data (evidence: `js/state.js`)
- API client → Auth storage: reads session (evidence: `js/api.js`)
- HTTP application → Public booking: mounts (evidence: `backend/src/app.js`)
- HTTP application → Session routes: mounts (evidence: `backend/src/app.js`)
- HTTP application → Auth middleware: requires authentication (evidence: `backend/src/app.js`)
- HTTP application → Availability API: mounts (evidence: `backend/src/app.js`)
- HTTP application → Operational routes: mounts (evidence: `backend/src/app.js`)
- Auth middleware → Identity provider: authenticates with (evidence: `backend/src/middleware/auth.js`)
- Auth middleware → Identity store: looks up identity (evidence: `backend/src/middleware/auth.js`)
- Session routes → Auth middleware: uses (evidence: `backend/src/routes/auth.js`)
- Session routes → Tenant repository: uses (evidence: `backend/src/routes/auth.js`)
- Availability rules → Schedule rules: uses (evidence: `backend/src/engines/DisponibilidadeEngine.js`)
- Slot suggestions → Schedule rules: uses (evidence: `backend/src/engines/SlotEngine.js`)
- Slot suggestions → Availability rules: computes from (evidence: `backend/src/engines/SlotEngine.js`)
- Appointment handling → Schedule rules: uses (evidence: `backend/src/engines/AtendimentoEngine.js`)
- Appointment handling → Slot suggestions: uses (evidence: `backend/src/engines/AtendimentoEngine.js`)
- Tenant repository → Supabase database: queries (evidence: `backend/src/repositories/SupabaseRepository.js`)
- Online customer → Public booking: books online
