# allail-qadrillah/ace-intelliegent-mobile-agent-system architecture

> Architecture diagram of the GitHub repository allail-qadrillah/ace-intelliegent-mobile-agent-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/allail-qadrillah/ace-intelliegent-mobile-agent-system
- Repository: https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system

## Overview

ACE is an offline Streamlit hotel-service simulation. Guests or staff use the interface to launch a scenario; the simulation coordinates agents through a case, policy checks, and (for room changes) candidate search, physical-readiness inspection, guest consent, a fresh readiness check, and an atomic reservation update. Other documented paths cover billing and manager escalation, concierge FAQs, housekeeping tickets, batch scenarios, and evaluation. The two SQLite stores and logical mobile-agent state migration are local to one Python process—not external services or physical server transfers. Some subsystem links rely on README capabilities because their implementations were not sampled.

Main entry points: [`hotel_demo/agents/orchestrator.py`](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/orchestrator.py) (Case orchestrator), [`hotel_demo/simulation.py`](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/simulation.py) (Simulation engine), [`hotel_demo/repository.py`](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/repository.py) (Hotel repositories), [`hotel_demo/ui.py`](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/ui.py) (Hotel interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Hotel experience"]
  node_app["Streamlit entry<br/>[app.py]"]
  node_ui["Hotel interface<br/>[ui.py]"]
  node_scenario_data["Scenario data<br/>[scenarios.json]"]
end

subgraph group_coordination["Case coordination"]
  node_simulation["Simulation engine<br/>[simulation.py]"]
  node_orchestrator["Case orchestrator<br/>[orchestrator.py]"]
  node_evaluation["Scenario evaluation<br/>[evaluation.py]"]
  node_ml["Human-review model<br/>[ml.py]"]
end

subgraph group_agents["Domain agents"]
  node_reservation["Reservation agent<br/>[reservation.py]"]
  node_investigator["Mobile investigator"]
  node_operations["Operations agent<br/>[operations.py]"]
  node_billing["Billing agent<br/>[billing.py]"]
  node_concierge["Concierge agent<br/>[concierge.py]"]
end

subgraph group_state["State and policy"]
  node_migration["State migration<br/>[migration.py]"]
  node_policy["Policy guardrails<br/>[policy.py]"]
  node_repository[("Hotel repositories<br/>[repository.py]")]
  node_seed["Hotel seed data<br/>[hotel_seed.json]"]
end

node_guest(("Hotel guest"))
node_staff(("Hotel staff"))

node_guest -->|"uses guest portal"| node_ui
node_staff -->|"uses staff tools"| node_ui
node_app -->|"renders views"| node_ui
node_ui -->|"starts and controls"| node_simulation
node_ui -->|"runs scenarios"| node_evaluation
node_simulation -->|"loads scenarios"| node_scenario_data
node_simulation -->|"loads seed"| node_seed
node_simulation -->|"initializes stores"| node_repository
node_simulation -->|"dispatches messages"| node_orchestrator
node_orchestrator -->|"predicts review need"| node_ml
node_orchestrator -->|"requests room actions"| node_reservation
node_orchestrator -->|"requests tickets"| node_operations
node_orchestrator -->|"requests folio lookup"| node_billing
node_orchestrator -->|"requests FAQ"| node_concierge
node_orchestrator -->|"starts inspection"| node_investigator
node_investigator -->|"starts state transfer"| node_migration
node_investigator -->|"inspects readiness"| node_operations
node_reservation -->|"finds and commits rooms"| node_repository
node_operations -->|"reads readiness and writes tickets"| node_repository
node_billing -->|"reads folio"| node_repository
node_concierge -->|"reads FAQ"| node_repository
node_repository -->|"validates room commit"| node_policy
node_evaluation -->|"runs scenarios"| node_simulation

click node_app "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/app.py"
click node_ui "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/ui.py"
click node_scenario_data "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/data/scenarios.json"
click node_simulation "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/simulation.py"
click node_orchestrator "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/orchestrator.py"
click node_evaluation "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/evaluation.py"
click node_ml "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/ml.py"
click node_reservation "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/reservation.py"
click node_investigator "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/mobile_investigator.py"
click node_operations "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/operations.py"
click node_billing "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/billing.py"
click node_concierge "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/concierge.py"
click node_migration "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/migration.py"
click node_policy "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/policy.py"
click node_repository "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/repository.py"
click node_seed "https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/data/hotel_seed.json"

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_app,node_ui,node_scenario_data toneBlue
class node_simulation,node_orchestrator,node_evaluation,node_ml toneAmber
class node_reservation,node_investigator,node_operations,node_billing,node_concierge toneMint
class node_migration,node_policy,node_repository,node_seed toneRose
class node_guest,node_staff toneIndigo
```

## Components

### Hotel experience

- [Streamlit entry](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/app.py): `app.py`
- [Hotel interface](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/ui.py): `hotel_demo/ui.py`
- [Scenario data](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/data/scenarios.json): `data/scenarios.json`

### Case coordination

- [Simulation engine](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/simulation.py): `hotel_demo/simulation.py`
- [Case orchestrator](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/orchestrator.py): `hotel_demo/agents/orchestrator.py`
- [Scenario evaluation](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/evaluation.py): `hotel_demo/evaluation.py`
- [Human-review model](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/ml.py): `hotel_demo/ml.py`

### Domain agents

- [Reservation agent](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/reservation.py): `hotel_demo/agents/reservation.py`
- [Mobile investigator](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/mobile_investigator.py): `hotel_demo/agents/mobile_investigator.py`
- [Operations agent](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/operations.py): `hotel_demo/agents/operations.py`
- [Billing agent](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/billing.py): `hotel_demo/agents/billing.py`
- [Concierge agent](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/agents/concierge.py): `hotel_demo/agents/concierge.py`

### State and policy

- [State migration](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/migration.py): `hotel_demo/migration.py`
- [Policy guardrails](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/policy.py): `hotel_demo/policy.py`
- [Hotel repositories](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/hotel_demo/repository.py): `hotel_demo/repository.py`
- [Hotel seed data](https://github.com/allail-qadrillah/ace-intelliegent-mobile-agent-system/blob/master/data/hotel_seed.json): `data/hotel_seed.json`

### Other components

- **Hotel guest**
- **Hotel staff**

## Connections

- Hotel guest → Hotel interface: uses guest portal
- Hotel staff → Hotel interface: uses staff tools
- Streamlit entry → Hotel interface: renders views
- Hotel interface → Simulation engine: starts and controls
- Hotel interface → Scenario evaluation: runs scenarios
- Simulation engine → Scenario data: loads scenarios
- Simulation engine → Hotel seed data: loads seed
- Simulation engine → Hotel repositories: initializes stores
- Simulation engine → Case orchestrator: dispatches messages
- Case orchestrator → Human-review model: predicts review need
- Case orchestrator → Reservation agent: requests room actions
- Case orchestrator → Operations agent: requests tickets
- Case orchestrator → Billing agent: requests folio lookup
- Case orchestrator → Concierge agent: requests FAQ
- Case orchestrator → Mobile investigator: starts inspection
- Mobile investigator → State migration: starts state transfer
- Mobile investigator → Operations agent: inspects readiness
- Reservation agent → Hotel repositories: finds and commits rooms
- Operations agent → Hotel repositories: reads readiness and writes tickets
- Billing agent → Hotel repositories: reads folio
- Concierge agent → Hotel repositories: reads FAQ
- Hotel repositories → Policy guardrails: validates room commit
- Scenario evaluation → Simulation engine: runs scenarios