# hotelsfidato-ai/crs architecture

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

- Interactive diagram: https://gitdiagram.com/hotelsfidato-ai/crs
- Repository: https://github.com/hotelsfidato-ai/crs

## Overview

#### Purpose and Runtime
Fidato is a Phase 1 internal hospitality CRS/ERP frontend for CRM, reservations, hotel inventory/rates, finance, reports, automation, and administration. It is a Vite-served React 19 TypeScript SPA with no backend or authentication; all interactions use deterministic simulated data that resets on refresh. Primary bootstrap and route entry points are `src/main.tsx` and `src/routes.tsx`.

#### Application Shell and Navigation
The routed application is framed by a shared operational shell: sidebar navigation, top bar, role switcher, command palette, and AI panel. This is the principal cross-feature control boundary, including simulated “Viewing as…” role context rather than login.
- `src/components/app/AppShell.tsx`
- `src/components/app/navigation.ts`
- `src/components/app/RoleSwitcher.tsx`

#### Routing, Access, and Failure States
`src/routes.tsx` maps the feature pages into the SPA. Authorization is client-side and driven by role/permission rules; forbidden, missing-route, and route-loading/error fallback states are isolated in the shared feature area. This is presentation-level enforcement only until real authentication arrives.
- `src/routes.tsx`
- `src/lib/permissions.ts`
- `src/features/shared/Forbidden.tsx`

#### Data Boundary: Repositories and Deterministic Mock State
Feature screens should consume the repository layer rather than directly owning persistence behavior. The current repository implementation is an in-memory mock store populated from fixed seed data, creating repeatable review flows and reset-on-refresh semantics. This is the intended Phase 2 swap boundary for Firestore-backed implementations.
- `src/data/repositories/index.ts`
- `src/data/repositories/mock/store.ts`
- `src/data/seed/index.ts`

#### Core Domain Feature Areas
The UI is organized by business capability, with route-level pages covering the major operating workflows: CRM entities and imports/merges; reservations, calendar, approvals, and booking details; partner hotel profiles, inventory, and rates; and finance invoices, payments, and commissions.
- `src/features/crm/CustomersPage.tsx`
- `src/features/reservations/ReservationsPage.tsx`
- `src/features/hotels/InventoryPage.tsx`
- `src/features/finance/InvoicesPage.tsx`

#### Analytics, Automation, AI, and Administration
Dashboard and reporting pages expose operational reporting, including occupancy, revenue, sales, forecast, and hotel views. Separate areas represent automation workflows/runs, simulated AI interactions, notifications/templates, and administrative users, roles, settings, integrations, and audit logs. These are frontend workflows today, not connected service integrations.
- `src/features/reports/ReportShell.tsx`
- `src/features/automation/WorkflowsPage.tsx`
- `src/features/ai/AiPage.tsx`
- `src/features/admin/IntegrationsPage.tsx`

#### Shared UI System and Future Infrastructure
A reusable UI layer supplies form controls, tables, filtering, overlays, status indicators, and feedback states; global styling and design tokens live separately. The material runtime stack includes React Router, TanStack Query, Zustand, Radix UI, react-hook-form/Zod, Recharts, Tailwind v4, and Vite. Planned infrastructure—not present in this build—is Firebase (Firestore, Auth, Functions, Storage), followed by n8n automation wiring.
- `src/components/ui/index.ts`
- `src/styles/theme.css`
- `docs/data-model.md`

Main entry points: [`src/routes.tsx`](https://github.com/hotelsfidato-ai/crs/blob/main/src/routes.tsx) (Route map), [`src/data/repositories/index.ts`](https://github.com/hotelsfidato-ai/crs/blob/main/src/data/repositories/index.ts) (Repository contracts), [`src/components/app/AppShell.tsx`](https://github.com/hotelsfidato-ai/crs/blob/main/src/components/app/AppShell.tsx) (Operational shell), [`src/lib/permissions.ts`](https://github.com/hotelsfidato-ai/crs/blob/main/src/lib/permissions.ts) (Client permissions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["SPA Runtime"]
  node_bootstrap(("Vite bootstrap<br/>entry point<br/>[main.tsx]"))
end

subgraph group_app["Application Control"]
  node_routes["Route map<br/>React Router<br/>[routes.tsx]"]
  node_shell["Operational shell<br/>shared layout<br/>[AppShell.tsx]"]
  node_navigation["Navigation model<br/>navigation config<br/>[navigation.ts]"]
  node_role_switcher["Role switcher<br/>simulated role context<br/>[RoleSwitcher.tsx]"]
  node_permissions["Client permissions<br/>access rules<br/>[permissions.ts]"]
  node_forbidden["Route failure states<br/>fallback UI<br/>[Forbidden.tsx]"]
end

subgraph group_data["Data Boundary"]
  node_repositories{{"Repository contracts<br/>data access boundary<br/>[index.ts]"}}
  node_mock_store[("In-memory mock store<br/>mock persistence<br/>[store.ts]")]
  node_seed_data["Fixed seed data<br/>deterministic fixtures<br/>[index.ts]"]
end

subgraph group_features["Business Features"]
  node_crm["CRM<br/>feature pages<br/>[CustomersPage.tsx]"]
  node_reservations["Reservations<br/>feature pages"]
  node_hotels["Hotel inventory<br/>feature pages<br/>[InventoryPage.tsx]"]
  node_finance["Finance<br/>feature pages<br/>[InvoicesPage.tsx]"]
  node_reports["Reports<br/>analytics pages<br/>[ReportShell.tsx]"]
  node_automation["Automation<br/>workflow pages<br/>[WorkflowsPage.tsx]"]
  node_ai_admin["AI and administration<br/>frontend workflows<br/>[AiPage.tsx]"]
  node_admin_integrations["Integration admin<br/>admin page"]
end

subgraph group_platform["Shared Platform"]
  node_ui_system["Shared UI system<br/>component library<br/>[index.ts]"]
  node_theme["Theme and tokens<br/>global styles<br/>[theme.css]"]
  node_future_model["Future data model<br/>planned infrastructure<br/>[data-model.md]"]
end

node_bootstrap -->|"mounts"| node_routes
node_routes -->|"frames routes"| node_shell
node_shell -->|"uses"| node_navigation
node_shell -->|"hosts"| node_role_switcher
node_routes -->|"checks access"| node_permissions
node_permissions -->|"denies to"| node_forbidden
node_routes -->|"routes to"| node_crm
node_routes -->|"routes to"| node_reservations
node_routes -->|"routes to"| node_hotels
node_routes -->|"routes to"| node_finance
node_routes -->|"routes to"| node_reports
node_routes -->|"routes to"| node_automation
node_routes -->|"routes to"| node_ai_admin
node_ai_admin -->|"includes"| node_admin_integrations
node_crm -->|"reads and writes"| node_repositories
node_reservations -->|"reads and writes"| node_repositories
node_hotels -->|"reads and writes"| node_repositories
node_finance -->|"reads and writes"| node_repositories
node_reports -->|"reads"| node_repositories
node_repositories -->|"implemented by"| node_mock_store
node_mock_store -->|"initialized from"| node_seed_data
node_ui_system -->|"styled by"| node_theme
node_repositories -.->|"planned evolution"| node_future_model

click node_bootstrap "https://github.com/hotelsfidato-ai/crs/blob/main/src/main.tsx"
click node_routes "https://github.com/hotelsfidato-ai/crs/blob/main/src/routes.tsx"
click node_shell "https://github.com/hotelsfidato-ai/crs/blob/main/src/components/app/AppShell.tsx"
click node_navigation "https://github.com/hotelsfidato-ai/crs/blob/main/src/components/app/navigation.ts"
click node_role_switcher "https://github.com/hotelsfidato-ai/crs/blob/main/src/components/app/RoleSwitcher.tsx"
click node_permissions "https://github.com/hotelsfidato-ai/crs/blob/main/src/lib/permissions.ts"
click node_forbidden "https://github.com/hotelsfidato-ai/crs/blob/main/src/features/shared/Forbidden.tsx"
click node_repositories "https://github.com/hotelsfidato-ai/crs/blob/main/src/data/repositories/index.ts"
click node_mock_store "https://github.com/hotelsfidato-ai/crs/blob/main/src/data/repositories/mock/store.ts"
click node_seed_data "https://github.com/hotelsfidato-ai/crs/blob/main/src/data/seed/index.ts"
click node_crm "https://github.com/hotelsfidato-ai/crs/blob/main/src/features/crm/CustomersPage.tsx"
click node_reservations "https://github.com/hotelsfidato-ai/crs/blob/main/src/features/reservations/ReservationsPage.tsx"
click node_hotels "https://github.com/hotelsfidato-ai/crs/blob/main/src/features/hotels/InventoryPage.tsx"
click node_finance "https://github.com/hotelsfidato-ai/crs/blob/main/src/features/finance/InvoicesPage.tsx"
click node_reports "https://github.com/hotelsfidato-ai/crs/blob/main/src/features/reports/ReportShell.tsx"
click node_automation "https://github.com/hotelsfidato-ai/crs/blob/main/src/features/automation/WorkflowsPage.tsx"
click node_ai_admin "https://github.com/hotelsfidato-ai/crs/blob/main/src/features/ai/AiPage.tsx"
click node_admin_integrations "https://github.com/hotelsfidato-ai/crs/blob/main/src/features/admin/IntegrationsPage.tsx"
click node_ui_system "https://github.com/hotelsfidato-ai/crs/blob/main/src/components/ui/index.ts"
click node_theme "https://github.com/hotelsfidato-ai/crs/blob/main/src/styles/theme.css"
click node_future_model "https://github.com/hotelsfidato-ai/crs/blob/main/docs/data-model.md"

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_bootstrap toneBlue
class node_routes,node_shell,node_navigation,node_role_switcher,node_permissions,node_forbidden toneAmber
class node_repositories,node_mock_store,node_seed_data toneMint
class node_crm,node_reservations,node_hotels,node_finance,node_reports,node_automation,node_ai_admin,node_admin_integrations toneRose
class node_ui_system,node_theme,node_future_model toneIndigo
```

## Components

### SPA Runtime

- [Vite bootstrap](https://github.com/hotelsfidato-ai/crs/blob/main/src/main.tsx): entry point · Starts the React SPA. · `src/main.tsx`

### Application Control

- [Route map](https://github.com/hotelsfidato-ai/crs/blob/main/src/routes.tsx): React Router · Maps feature pages and route fallbacks. · `src/routes.tsx`
- [Operational shell](https://github.com/hotelsfidato-ai/crs/blob/main/src/components/app/AppShell.tsx): shared layout · Frames routes with navigation, top bar, command palette, and AI panel. · `src/components/app/AppShell.tsx`
- [Navigation model](https://github.com/hotelsfidato-ai/crs/blob/main/src/components/app/navigation.ts): navigation config · `src/components/app/navigation.ts`
- [Role switcher](https://github.com/hotelsfidato-ai/crs/blob/main/src/components/app/RoleSwitcher.tsx): simulated role context · Provides the “Viewing as…” context. · `src/components/app/RoleSwitcher.tsx`
- [Client permissions](https://github.com/hotelsfidato-ai/crs/blob/main/src/lib/permissions.ts): access rules · Presentation-level route authorization. · `src/lib/permissions.ts`
- [Route failure states](https://github.com/hotelsfidato-ai/crs/blob/main/src/features/shared/Forbidden.tsx): fallback UI · Includes forbidden and missing/error route states. · `src/features/shared/Forbidden.tsx`

### Data Boundary

- [Repository contracts](https://github.com/hotelsfidato-ai/crs/blob/main/src/data/repositories/index.ts): data access boundary · Phase 2 swap point for Firestore implementations. · `src/data/repositories/index.ts`
- [In-memory mock store](https://github.com/hotelsfidato-ai/crs/blob/main/src/data/repositories/mock/store.ts): mock persistence · State resets on refresh. · `src/data/repositories/mock/store.ts`
- [Fixed seed data](https://github.com/hotelsfidato-ai/crs/blob/main/src/data/seed/index.ts): deterministic fixtures · Makes review flows repeatable. · `src/data/seed/index.ts`

### Business Features

- [CRM](https://github.com/hotelsfidato-ai/crs/blob/main/src/features/crm/CustomersPage.tsx): feature pages · Customers, imports, and merges. · `src/features/crm/CustomersPage.tsx`
- [Reservations](https://github.com/hotelsfidato-ai/crs/blob/main/src/features/reservations/ReservationsPage.tsx): feature pages · Bookings, calendar, approvals, and details. · `src/features/reservations/ReservationsPage.tsx`
- [Hotel inventory](https://github.com/hotelsfidato-ai/crs/blob/main/src/features/hotels/InventoryPage.tsx): feature pages · Partner profiles, inventory, and rates. · `src/features/hotels/InventoryPage.tsx`
- [Finance](https://github.com/hotelsfidato-ai/crs/blob/main/src/features/finance/InvoicesPage.tsx): feature pages · Invoices, payments, and commissions. · `src/features/finance/InvoicesPage.tsx`
- [Reports](https://github.com/hotelsfidato-ai/crs/blob/main/src/features/reports/ReportShell.tsx): analytics pages · Operational occupancy, revenue, sales, forecast, and hotel reporting. · `src/features/reports/ReportShell.tsx`
- [Automation](https://github.com/hotelsfidato-ai/crs/blob/main/src/features/automation/WorkflowsPage.tsx): workflow pages · Simulated workflows and runs. · `src/features/automation/WorkflowsPage.tsx`
- [AI and administration](https://github.com/hotelsfidato-ai/crs/blob/main/src/features/ai/AiPage.tsx): frontend workflows · Simulated AI plus integrations, users, roles, settings, and audit administration. · `src/features/ai/AiPage.tsx`
- [Integration admin](https://github.com/hotelsfidato-ai/crs/blob/main/src/features/admin/IntegrationsPage.tsx): admin page · Frontend-only integration management. · `src/features/admin/IntegrationsPage.tsx`

### Shared Platform

- [Shared UI system](https://github.com/hotelsfidato-ai/crs/blob/main/src/components/ui/index.ts): component library · Controls, tables, filters, overlays, indicators, and feedback. · `src/components/ui/index.ts`
- [Theme and tokens](https://github.com/hotelsfidato-ai/crs/blob/main/src/styles/theme.css): global styles · `src/styles/theme.css`
- [Future data model](https://github.com/hotelsfidato-ai/crs/blob/main/docs/data-model.md): planned infrastructure · Documents the future Firebase-backed architecture. · `docs/data-model.md`

## Connections

- Vite bootstrap → Route map: mounts
- Route map → Operational shell: frames routes
- Operational shell → Navigation model: uses
- Operational shell → Role switcher: hosts
- Route map → Client permissions: checks access
- Client permissions → Route failure states: denies to
- Route map → CRM: routes to
- Route map → Reservations: routes to
- Route map → Hotel inventory: routes to
- Route map → Finance: routes to
- Route map → Reports: routes to
- Route map → Automation: routes to
- Route map → AI and administration: routes to
- AI and administration → Integration admin: includes
- CRM → Repository contracts: reads and writes
- Reservations → Repository contracts: reads and writes
- Hotel inventory → Repository contracts: reads and writes
- Finance → Repository contracts: reads and writes
- Reports → Repository contracts: reads
- Repository contracts → In-memory mock store: implemented by
- In-memory mock store → Fixed seed data: initialized from
- Shared UI system → Theme and tokens: styled by
- Repository contracts → Future data model: planned evolution