# josuemerlos/ceiba architecture

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

- Interactive diagram: https://gitdiagram.com/josuemerlos/ceiba
- Repository: https://github.com/josuemerlos/ceiba

## Overview

Ceiba is a multi-tenant service-business platform whose first product is Ceiba Citas. Its main user journeys are staff managing appointment catalogs and schedules in the panel, and customers discovering a business and booking through the public app; Rails packs provide API and domain behavior. The graph preserves the documented identity, tenancy, customer, access, and branding capabilities. Several backend and booking subsystems are represented by tree-supported paths, but their internal calls were not sampled, so those links are marked unverified or omitted.

Main entry points: [`backend/config/application.rb`](https://github.com/josuemerlos/ceiba/blob/main/backend/config/application.rb) (Rails API runtime), [`backend/packs/modules/appointments/app/controllers/api/v1/appointments/appointments_controller.rb`](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/modules/appointments/app/controllers/api/v1/appointments/appointments_controller.rb) (Appointment API), [`backend/packs/modules/appointments/app/models/appointments/appointment.rb`](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/modules/appointments/app/models/appointments/appointment.rb) (Appointment records), [`frontend/apps/panel/src/app/app.tsx`](https://github.com/josuemerlos/ceiba/blob/main/frontend/apps/panel/src/app/app.tsx) (Staff panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["User applications"]
  node_staff["Staff panel<br/>[app.tsx]"]
  node_catalog_ui["Service catalog UI<br/>[services-page.tsx]"]
  node_booking_ui["Public booking app<br/>[App.tsx]"]
end

subgraph group_appointments["Appointments domain"]
  node_appointment_api["Appointment API"]
  node_availability_api["Availability endpoints"]
  node_booking_commands["Booking lifecycle"]
  node_availability_engine["Availability engine"]
  node_catalog_services["Service catalog"]
  node_staff_services["Staff scheduling"]
  node_appointment_models[("Appointment records<br/>[appointment.rb]")]
end

subgraph group_platform["Platform services"]
  node_identity["Identity and sessions"]
  node_access["Branch access"]
  node_customers["Customer accounts"]
  node_modules["Module activation<br/>[me_controller.rb]"]
  node_tenancy_branding["Tenant branding"]
  node_media_storage["Branding media"]
end

subgraph group_shared["API foundation"]
  node_api_client["Typed API client<br/>[client.ts]"]
  node_query_hooks["API query hooks<br/>[query.tsx]"]
  node_rails_api["Rails API runtime<br/>[application.rb]"]
end

node_postgres[("PostgreSQL")]
node_customer(("Booking customer"))
node_staff_user(("Business staff"))

node_staff -->|"renders routes"| node_catalog_ui
node_catalog_ui -.->|"uses queries"| node_query_hooks
node_query_hooks -->|"calls client"| node_api_client
node_api_client -->|"sends API requests"| node_rails_api
node_customer -.->|"opens booking"| node_booking_ui
node_booking_ui -.->|"loads branding"| node_tenancy_branding
node_staff_user -.->|"uses panel"| node_staff
node_rails_api -.->|"routes requests"| node_appointment_api
node_rails_api -.->|"routes requests"| node_availability_api
node_appointment_api -.->|"manages lifecycle"| node_booking_commands
node_availability_api -.->|"calculates slots"| node_availability_engine
node_appointment_api -.->|"reads and writes"| node_appointment_models
node_booking_commands -.->|"creates appointments"| node_appointment_models
node_appointment_api -.->|"manages services"| node_catalog_services
node_appointment_api -.->|"manages schedules"| node_staff_services
node_rails_api -.->|"routes requests"| node_identity
node_rails_api -.->|"routes requests"| node_access
node_rails_api -.->|"routes requests"| node_customers
node_rails_api -.->|"routes requests"| node_modules
node_tenancy_branding -.->|"uses attachments"| node_media_storage
node_appointment_models -.->|"persists records"| node_postgres

click node_staff "https://github.com/josuemerlos/ceiba/blob/main/frontend/apps/panel/src/app/app.tsx"
click node_catalog_ui "https://github.com/josuemerlos/ceiba/blob/main/frontend/apps/panel/src/modules/appointments/routes/services-page.tsx"
click node_booking_ui "https://github.com/josuemerlos/ceiba/blob/main/frontend/apps/booking/src/App.tsx"
click node_api_client "https://github.com/josuemerlos/ceiba/blob/main/frontend/packages/api-client/src/client.ts"
click node_query_hooks "https://github.com/josuemerlos/ceiba/blob/main/frontend/packages/api-client/src/query.tsx"
click node_appointment_api "https://github.com/josuemerlos/ceiba/blob/main/backend/packs/modules/appointments/app/controllers/api/v1/appointments/appointments_controller.rb"
click node_availability_api "https://github.com/josuemerlos/ceiba/blob/main/backend/packs/modules/appointments/app/controllers/api/public/v1/appointments/availability_controller.rb"
click node_booking_commands "https://github.com/josuemerlos/ceiba/tree/main/backend/packs/modules/appointments/app/public/appointments"
click node_availability_engine "https://github.com/josuemerlos/ceiba/tree/main/backend/packs/modules/appointments/app/services/appointments/availability"
click node_catalog_services "https://github.com/josuemerlos/ceiba/tree/main/backend/packs/modules/appointments/app/services/appointments/catalog"
click node_staff_services "https://github.com/josuemerlos/ceiba/tree/main/backend/packs/modules/appointments/app/services/appointments/staff"
click node_appointment_models "https://github.com/josuemerlos/ceiba/blob/main/backend/packs/modules/appointments/app/models/appointments/appointment.rb"
click node_identity "https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/identity/app/controllers/api/v1/identity/sessions_controller.rb"
click node_access "https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/access/app/controllers/api/v1/access/branches_controller.rb"
click node_customers "https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/customers/app/controllers/api/v1/customers/customers_controller.rb"
click node_modules "https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/modules/app/controllers/api/v1/modules/me_controller.rb"
click node_tenancy_branding "https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/tenancy/app/controllers/api/public/v1/tenancy/brandings_controller.rb"
click node_media_storage "https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/tenancy/app/controllers/tenancy/storage/representations_controller.rb"
click node_rails_api "https://github.com/josuemerlos/ceiba/blob/main/backend/config/application.rb"

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_staff,node_catalog_ui,node_booking_ui toneBlue
class node_appointment_api,node_availability_api,node_booking_commands,node_availability_engine,node_catalog_services,node_staff_services,node_appointment_models,node_postgres toneAmber
class node_identity,node_access,node_customers,node_modules,node_tenancy_branding,node_media_storage toneMint
class node_api_client,node_query_hooks,node_rails_api toneRose
class node_customer,node_staff_user toneIndigo
```

## Components

### User applications

- [Staff panel](https://github.com/josuemerlos/ceiba/blob/main/frontend/apps/panel/src/app/app.tsx): `frontend/apps/panel/src/app/app.tsx`
- [Service catalog UI](https://github.com/josuemerlos/ceiba/blob/main/frontend/apps/panel/src/modules/appointments/routes/services-page.tsx): `frontend/apps/panel/src/modules/appointments/routes/services-page.tsx`
- [Public booking app](https://github.com/josuemerlos/ceiba/blob/main/frontend/apps/booking/src/App.tsx): `frontend/apps/booking/src/App.tsx`

### Appointments domain

- [Appointment API](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/modules/appointments/app/controllers/api/v1/appointments/appointments_controller.rb): `backend/packs/modules/appointments/app/controllers/api/v1/appointments/appointments_controller.rb`
- [Availability endpoints](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/modules/appointments/app/controllers/api/public/v1/appointments/availability_controller.rb): `backend/packs/modules/appointments/app/controllers/api/public/v1/appointments/availability_controller.rb`
- [Booking lifecycle](https://github.com/josuemerlos/ceiba/tree/main/backend/packs/modules/appointments/app/public/appointments): `backend/packs/modules/appointments/app/public/appointments`
- [Availability engine](https://github.com/josuemerlos/ceiba/tree/main/backend/packs/modules/appointments/app/services/appointments/availability): `backend/packs/modules/appointments/app/services/appointments/availability`
- [Service catalog](https://github.com/josuemerlos/ceiba/tree/main/backend/packs/modules/appointments/app/services/appointments/catalog): `backend/packs/modules/appointments/app/services/appointments/catalog`
- [Staff scheduling](https://github.com/josuemerlos/ceiba/tree/main/backend/packs/modules/appointments/app/services/appointments/staff): `backend/packs/modules/appointments/app/services/appointments/staff`
- [Appointment records](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/modules/appointments/app/models/appointments/appointment.rb): `backend/packs/modules/appointments/app/models/appointments/appointment.rb`

### Platform services

- [Identity and sessions](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/identity/app/controllers/api/v1/identity/sessions_controller.rb): `backend/packs/platform/identity/app/controllers/api/v1/identity/sessions_controller.rb`
- [Branch access](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/access/app/controllers/api/v1/access/branches_controller.rb): `backend/packs/platform/access/app/controllers/api/v1/access/branches_controller.rb`
- [Customer accounts](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/customers/app/controllers/api/v1/customers/customers_controller.rb): `backend/packs/platform/customers/app/controllers/api/v1/customers/customers_controller.rb`
- [Module activation](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/modules/app/controllers/api/v1/modules/me_controller.rb): `backend/packs/platform/modules/app/controllers/api/v1/modules/me_controller.rb`
- [Tenant branding](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/tenancy/app/controllers/api/public/v1/tenancy/brandings_controller.rb): `backend/packs/platform/tenancy/app/controllers/api/public/v1/tenancy/brandings_controller.rb`
- [Branding media](https://github.com/josuemerlos/ceiba/blob/main/backend/packs/platform/tenancy/app/controllers/tenancy/storage/representations_controller.rb): `backend/packs/platform/tenancy/app/controllers/tenancy/storage/representations_controller.rb`

### API foundation

- [Typed API client](https://github.com/josuemerlos/ceiba/blob/main/frontend/packages/api-client/src/client.ts): `frontend/packages/api-client/src/client.ts`
- [API query hooks](https://github.com/josuemerlos/ceiba/blob/main/frontend/packages/api-client/src/query.tsx): `frontend/packages/api-client/src/query.tsx`
- [Rails API runtime](https://github.com/josuemerlos/ceiba/blob/main/backend/config/application.rb): `backend/config/application.rb`

### Other components

- **PostgreSQL**
- **Booking customer**
- **Business staff**

## Connections

- Staff panel → Service catalog UI: renders routes (evidence: `frontend/apps/panel/src/app/app.tsx`)
- Service catalog UI → API query hooks: uses queries
- API query hooks → Typed API client: calls client (evidence: `frontend/packages/api-client/src/query.tsx`)
- Typed API client → Rails API runtime: sends API requests (evidence: `frontend/packages/api-client/src/client.ts`)
- Booking customer → Public booking app: opens booking
- Public booking app → Tenant branding: loads branding
- Business staff → Staff panel: uses panel
- Rails API runtime → Appointment API: routes requests
- Rails API runtime → Availability endpoints: routes requests
- Appointment API → Booking lifecycle: manages lifecycle
- Availability endpoints → Availability engine: calculates slots
- Appointment API → Appointment records: reads and writes
- Booking lifecycle → Appointment records: creates appointments
- Appointment API → Service catalog: manages services
- Appointment API → Staff scheduling: manages schedules
- Rails API runtime → Identity and sessions: routes requests
- Rails API runtime → Branch access: routes requests
- Rails API runtime → Customer accounts: routes requests
- Rails API runtime → Module activation: routes requests
- Tenant branding → Branding media: uses attachments
- Appointment records → PostgreSQL: persists records
