# jay623949-dotcom/hack-celestial architecture

> Architecture diagram of the GitHub repository jay623949-dotcom/hack-celestial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jay623949-dotcom/hack-celestial
- Repository: https://github.com/jay623949-dotcom/hack-celestial

## Overview

RESORT 360 coordinates resort operations through a command center and AI-assisted workflow: operational state is assembled into context, analyzed by departmental agents, reconciled into recommendations, reviewed by a manager, and dispatched for execution. The repository also contains a Smart Resort Express implementation and a HackCel FastAPI/demo implementation with specialized department services and live events. Several connections in those parallel implementations are documented by imports or excerpts; unsampled behavior is not inferred.

Main entry points: [`backend/src/services/orchestrator.service.js`](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/orchestrator.service.js) (AI Orchestrator), [`backend/src/app.js`](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/app.js) (Express API), [`backend/src/smart-resort/routes.js`](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/smart-resort/routes.js) (Smart Resort Routes), [`HackCel/app/main.py`](https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/main.py) (FastAPI Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_command["Command Center"]
  node_dashboard["Operations Dashboard<br/>[page.js]"]
  node_webapi["REST API Client<br/>[api.js]"]
  node_api["Express API<br/>[app.js]"]
  node_plans["Action Plan Review"]
  node_live["Live Updates<br/>[socket.service.js]"]
end

subgraph group_intelligence["AI Decisioning"]
  node_ai_routes["AI Controller<br/>[ai.controller.js]"]
  node_context["Context Builder"]
  node_orchestrator["AI Orchestrator"]
  node_agents["Department Agents<br/>[agent.service.js]"]
  node_ai_provider["AI Provider<br/>[openai.service.js]"]
  node_consensus["Consensus Engine"]
  node_persistence[("AI Persistence")]
end

subgraph group_operations["Operational Services"]
  node_execution["Task Execution"]
  node_domain["Operational Services"]
  node_store[("Operational Data Store<br/>[dataStore.js]")]
end

subgraph group_smart["Smart Resort"]
  node_smart_routes["Smart Resort Routes<br/>[routes.js]"]
  node_smart_engine["Intelligence Engine<br/>[engine.service.js]"]
  node_smart_depts["Department Services"]
  node_smart_state[("Resort State")]
end

subgraph group_hackcel["HackCel Demo"]
  node_py_app["FastAPI Application<br/>[main.py]"]
  node_py_db[("SQLite Data Layer<br/>[db.py]")]
  node_py_maintenance["Maintenance Agent"]
  node_py_departments["Department Agents"]
  node_py_ai["Mock AI Client<br/>[mock_ai_client.py]"]
  node_py_events["Cross-Agent Events<br/>[event_bus.py]"]
  node_py_ui["Operations Demo UI<br/>[App.tsx]"]
  node_py_models["Operational Models<br/>[room.py]"]
end

node_manager(("Duty Manager"))

node_manager -->|"reviews operations"| node_dashboard
node_dashboard -->|"requests data"| node_webapi
node_webapi -.->|"calls API"| node_api
node_api -->|"mounts routes"| node_ai_routes
node_ai_routes -->|"invokes analysis"| node_orchestrator
node_orchestrator -->|"builds context"| node_context
node_context -->|"reads state"| node_store
node_orchestrator -->|"analyzes context"| node_ai_provider
node_orchestrator -->|"runs agents"| node_agents
node_agents -->|"requests inference"| node_ai_provider
node_orchestrator -->|"synthesizes results"| node_consensus
node_orchestrator -->|"persists results"| node_persistence
node_manager -->|"approves or edits"| node_plans
node_plans -.->|"dispatches approved plan"| node_execution
node_execution -->|"emits telemetry"| node_live
node_domain -.->|"uses operational state"| node_store
node_api -->|"mounts router"| node_smart_routes
node_smart_routes -->|"routes engine requests"| node_smart_engine
node_smart_routes -->|"routes department actions"| node_smart_depts
node_smart_engine -->|"reads state"| node_smart_state
node_py_ui -->|"posts operations"| node_py_app
node_py_app -->|"initializes database"| node_py_db
node_py_app -->|"registers subscribers"| node_py_departments
node_py_departments -->|"requests AI results"| node_py_ai
node_py_maintenance -->|"reads and writes"| node_py_db
node_py_departments -->|"publishes events"| node_py_events
node_py_db -->|"registers models"| node_py_models

click node_dashboard "https://github.com/jay623949-dotcom/hack-celestial/blob/main/frontend/app/dashboard/page.js"
click node_webapi "https://github.com/jay623949-dotcom/hack-celestial/blob/main/frontend/lib/api.js"
click node_api "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/app.js"
click node_ai_routes "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/controllers/ai.controller.js"
click node_context "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/context-builder.service.js"
click node_orchestrator "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/orchestrator.service.js"
click node_agents "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/agent.service.js"
click node_ai_provider "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/openai.service.js"
click node_consensus "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/consensus.service.js"
click node_persistence "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/ai-persistence.service.js"
click node_plans "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/controllers/actionPlans.controller.js"
click node_execution "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/execution.service.js"
click node_live "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/socket.service.js"
click node_domain "https://github.com/jay623949-dotcom/hack-celestial/tree/main/backend/src/services"
click node_store "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/data/dataStore.js"
click node_smart_routes "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/smart-resort/routes.js"
click node_smart_engine "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/smart-resort/engine.service.js"
click node_smart_depts "https://github.com/jay623949-dotcom/hack-celestial/tree/main/backend/src/smart-resort"
click node_smart_state "https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/smart-resort/smartResortStore.js"
click node_py_app "https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/main.py"
click node_py_db "https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/db.py"
click node_py_maintenance "https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/services/maintenance_service.py"
click node_py_departments "https://github.com/jay623949-dotcom/hack-celestial/tree/main/HackCel/app/services"
click node_py_ai "https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/ai/mock_ai_client.py"
click node_py_events "https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/event_bus.py"
click node_py_ui "https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/frontend/src/App.tsx"
click node_py_models "https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/models/room.py"

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_dashboard,node_webapi,node_api,node_plans,node_live toneBlue
class node_ai_routes,node_context,node_orchestrator,node_agents,node_ai_provider,node_consensus,node_persistence toneAmber
class node_execution,node_domain,node_store toneMint
class node_smart_routes,node_smart_engine,node_smart_depts,node_smart_state toneRose
class node_py_app,node_py_db,node_py_maintenance,node_py_departments,node_py_ai,node_py_events,node_py_ui,node_py_models,node_manager toneIndigo
```

## Components

### Command Center

- [Operations Dashboard](https://github.com/jay623949-dotcom/hack-celestial/blob/main/frontend/app/dashboard/page.js): `frontend/app/dashboard/page.js`
- [REST API Client](https://github.com/jay623949-dotcom/hack-celestial/blob/main/frontend/lib/api.js): `frontend/lib/api.js`
- [Express API](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/app.js): `backend/src/app.js`
- [Action Plan Review](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/controllers/actionPlans.controller.js): `backend/src/controllers/actionPlans.controller.js`
- [Live Updates](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/socket.service.js): `backend/src/services/socket.service.js`

### AI Decisioning

- [AI Controller](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/controllers/ai.controller.js): `backend/src/controllers/ai.controller.js`
- [Context Builder](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/context-builder.service.js): `backend/src/services/context-builder.service.js`
- [AI Orchestrator](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/orchestrator.service.js): `backend/src/services/orchestrator.service.js`
- [Department Agents](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/agent.service.js): `backend/src/services/agent.service.js`
- [AI Provider](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/openai.service.js): `backend/src/services/openai.service.js`
- [Consensus Engine](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/consensus.service.js): `backend/src/services/consensus.service.js`
- [AI Persistence](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/ai-persistence.service.js): `backend/src/services/ai-persistence.service.js`

### Operational Services

- [Task Execution](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/services/execution.service.js): `backend/src/services/execution.service.js`
- [Operational Services](https://github.com/jay623949-dotcom/hack-celestial/tree/main/backend/src/services): `backend/src/services`
- [Operational Data Store](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/data/dataStore.js): `backend/src/data/dataStore.js`

### Smart Resort

- [Smart Resort Routes](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/smart-resort/routes.js): `backend/src/smart-resort/routes.js`
- [Intelligence Engine](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/smart-resort/engine.service.js): `backend/src/smart-resort/engine.service.js`
- [Department Services](https://github.com/jay623949-dotcom/hack-celestial/tree/main/backend/src/smart-resort): `backend/src/smart-resort`
- [Resort State](https://github.com/jay623949-dotcom/hack-celestial/blob/main/backend/src/smart-resort/smartResortStore.js): `backend/src/smart-resort/smartResortStore.js`

### HackCel Demo

- [FastAPI Application](https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/main.py): `HackCel/app/main.py`
- [SQLite Data Layer](https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/db.py): `HackCel/app/db.py`
- [Maintenance Agent](https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/services/maintenance_service.py): `HackCel/app/services/maintenance_service.py`
- [Department Agents](https://github.com/jay623949-dotcom/hack-celestial/tree/main/HackCel/app/services): `HackCel/app/services`
- [Mock AI Client](https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/ai/mock_ai_client.py): `HackCel/app/ai/mock_ai_client.py`
- [Cross-Agent Events](https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/event_bus.py): `HackCel/app/event_bus.py`
- [Operations Demo UI](https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/frontend/src/App.tsx): `HackCel/frontend/src/App.tsx`
- [Operational Models](https://github.com/jay623949-dotcom/hack-celestial/blob/main/HackCel/app/models/room.py): `HackCel/app/models/room.py`

### Other components

- **Duty Manager**

## Connections

- Duty Manager → Operations Dashboard: reviews operations (evidence: `README.md`)
- Operations Dashboard → REST API Client: requests data
- REST API Client → Express API: calls API
- Express API → AI Controller: mounts routes (evidence: `backend/src/app.js`)
- AI Controller → AI Orchestrator: invokes analysis (evidence: `backend/src/controllers/ai.controller.js`)
- AI Orchestrator → Context Builder: builds context (evidence: `backend/src/services/orchestrator.service.js`)
- Context Builder → Operational Data Store: reads state (evidence: `backend/src/services/context-builder.service.js`)
- AI Orchestrator → AI Provider: analyzes context (evidence: `backend/src/services/orchestrator.service.js`)
- AI Orchestrator → Department Agents: runs agents (evidence: `backend/src/services/orchestrator.service.js`)
- Department Agents → AI Provider: requests inference (evidence: `backend/src/services/agent.service.js`)
- AI Orchestrator → Consensus Engine: synthesizes results (evidence: `backend/src/services/orchestrator.service.js`)
- AI Orchestrator → AI Persistence: persists results (evidence: `backend/src/services/orchestrator.service.js`)
- Duty Manager → Action Plan Review: approves or edits (evidence: `README.md`)
- Action Plan Review → Task Execution: dispatches approved plan
- Task Execution → Live Updates: emits telemetry
- Operational Services → Operational Data Store: uses operational state (evidence: `backend/src/services/context-builder.service.js`)
- Express API → Smart Resort Routes: mounts router (evidence: `backend/src/app.js`)
- Smart Resort Routes → Intelligence Engine: routes engine requests (evidence: `backend/src/smart-resort/routes.js`)
- Smart Resort Routes → Department Services: routes department actions (evidence: `backend/src/smart-resort/routes.js`)
- Intelligence Engine → Resort State: reads state (evidence: `backend/src/smart-resort/engine.service.js`)
- Operations Demo UI → FastAPI Application: posts operations (evidence: `HackCel/frontend/src/App.tsx`)
- FastAPI Application → SQLite Data Layer: initializes database (evidence: `HackCel/app/main.py`)
- FastAPI Application → Department Agents: registers subscribers (evidence: `HackCel/app/main.py`)
- Department Agents → Mock AI Client: requests AI results (evidence: `HackCel/app/services/frontdesk_service.py`)
- Maintenance Agent → SQLite Data Layer: reads and writes (evidence: `HackCel/app/services/maintenance_service.py`)
- Department Agents → Cross-Agent Events: publishes events (evidence: `HackCel/app/services/frontdesk_service.py`)
- SQLite Data Layer → Operational Models: registers models (evidence: `HackCel/app/db.py`)
