# aeron-marc/kaayos architecture

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

- Interactive diagram: https://gitdiagram.com/aeron-marc/kaayos
- Repository: https://github.com/aeron-marc/kaayos

## Overview

KaAyos is a Tuy, Batangas home-services marketplace. Clients discover workers and book services; workers manage jobs and schedules; administrators oversee verification, disputes, and reporting. Laravel routes requests into role-specific controllers and persists marketplace records through Eloquent models, while Reverb supports realtime updates and a separate FastAPI service provides matching and geospatial capabilities. The README documents major capabilities not represented by sampled implementation excerpts; those branches are included as documented subsystems, with relationships cited to the README where appropriate.

Main entry points: [`kaayos/routes/web.php`](https://github.com/aeron-marc/kaayos/blob/main/kaayos/routes/web.php) (Web routes), [`kaayos/app/Models`](https://github.com/aeron-marc/kaayos/tree/main/kaayos/app/Models) (Marketplace records), [`kaayos/app/Http/Controllers/Client/ClientController.php`](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Client/ClientController.php) (Client bookings), [`kaayos/app/Http/Controllers/SearchController.php`](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/SearchController.php) (Search and map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Worker Discovery"]
  node_discovery_search["Search and map"]
  node_public_profiles["Worker profiles"]
  node_geo_support["Local geospatial data<br/>[TuyBarangays.php]"]
end

subgraph group_marketplace["Booking and Work"]
  node_booking_client["Client bookings"]
  node_booking_lifecycle["Booking lifecycle<br/>[Booking.php]"]
  node_worker_dashboard["Worker job dashboard"]
  node_worker_tools["Worker services and schedule"]
  node_geo_travel["Travel and scheduling"]
  node_expired_command["Expired booking cancellation"]
end

subgraph group_roles["Accounts and Operations"]
  node_auth["Authentication and profiles"]
  node_verification["Worker verification"]
  node_admin_ops["Admin operations"]
  node_admin_reports["Reports and exports"]
end

subgraph group_assist["Realtime and AI"]
  node_chat["Messaging<br/>[Message.php]"]
  node_realtime["Realtime events"]
  node_chatbot["AI assistant<br/>[ChatBotService.php]"]
  node_suggestions["Worker suggestions"]
  node_ml_service["Matching microservice<br/>[main.py]"]
end

subgraph group_core["Application Core"]
  node_web_routes["Web routes<br/>[web.php]"]
  node_api_routes["API routes<br/>[api.php]"]
  node_market_models[("Marketplace records")]
  node_user_model[("User and worker profile<br/>[User.php]")]
  node_services_model[("Service catalog<br/>[Service.php]")]
  node_reviews_model[("Reviews and testimonials<br/>[Review.php]")]
end

node_visitor(("Client or visitor"))
node_worker_actor(("Worker"))
node_admin_actor(("Administrator"))
node_browser(("Browser client"))
node_reverb_service["Laravel Reverb"]
node_openrouter{{"OpenRouter"}}

node_visitor -->|"requests pages"| node_web_routes
node_worker_actor -->|"manages work"| node_web_routes
node_admin_actor -->|"administers platform"| node_web_routes
node_web_routes -->|"routes search"| node_discovery_search
node_web_routes -->|"routes profiles"| node_public_profiles
node_web_routes -->|"routes bookings"| node_booking_client
node_web_routes -->|"routes worker jobs"| node_worker_dashboard
node_web_routes -->|"routes worker tools"| node_worker_tools
node_web_routes -->|"routes authentication"| node_auth
node_web_routes -->|"routes verification"| node_verification
node_web_routes -->|"routes admin operations"| node_admin_ops
node_web_routes -->|"routes reporting"| node_admin_reports
node_visitor -->|"calls assistant API"| node_api_routes
node_api_routes -->|"routes suggestions"| node_suggestions
node_discovery_search -->|"queries workers"| node_market_models
node_discovery_search -->|"filters categories"| node_services_model
node_discovery_search -->|"uses barangays"| node_geo_support
node_public_profiles -->|"uses barangays"| node_geo_support
node_booking_client -->|"creates bookings"| node_booking_lifecycle
node_booking_client -->|"reads and writes records"| node_market_models
node_booking_client -->|"broadcasts status"| node_realtime
node_booking_client -->|"posts booking messages"| node_chat
node_booking_client -->|"submits reviews"| node_reviews_model
node_worker_dashboard -->|"updates status"| node_booking_lifecycle
node_worker_dashboard -->|"broadcasts status"| node_realtime
node_worker_dashboard -->|"posts booking messages"| node_chat
node_worker_tools -->|"builds routes"| node_geo_travel
node_worker_tools -->|"reads worker records"| node_market_models
node_booking_client -->|"checks feasibility"| node_geo_travel
node_expired_command -.->|"cancels stale bookings"| node_booking_lifecycle
node_auth -->|"creates accounts"| node_user_model
node_verification -.->|"verifies workers"| node_user_model
node_admin_ops -.->|"manages marketplace data"| node_market_models
node_admin_reports -->|"reports on activity"| node_market_models
node_admin_reports -.->|"includes review reports"| node_reviews_model
node_suggestions -->|"requests assistant reply"| node_chatbot
node_suggestions -->|"finds matching workers"| node_user_model
node_suggestions -.->|"requests matching"| node_ml_service
node_chatbot -.->|"calls AI provider"| node_openrouter
node_browser -.->|"receives live updates"| node_reverb_service
node_realtime -.->|"publishes events"| node_reverb_service
node_market_models -.->|"stores domain records"| node_user_model
node_booking_lifecycle -.->|"persists booking state"| node_market_models
node_services_model -.->|"stores catalog data"| node_market_models
node_reviews_model -.->|"stores feedback"| node_market_models

click node_web_routes "https://github.com/aeron-marc/kaayos/blob/main/kaayos/routes/web.php"
click node_api_routes "https://github.com/aeron-marc/kaayos/blob/main/kaayos/routes/api.php"
click node_discovery_search "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/SearchController.php"
click node_public_profiles "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Client/WorkerController.php"
click node_geo_support "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Support/TuyBarangays.php"
click node_booking_client "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Client/ClientController.php"
click node_booking_lifecycle "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Models/Booking.php"
click node_worker_dashboard "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Worker/WorkerDashboardController.php"
click node_worker_tools "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Worker/WorkerController.php"
click node_geo_travel "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Services/GeoTravelService.php"
click node_auth "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Auth/RegisterController.php"
click node_verification "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Admin/VerificationController.php"
click node_admin_ops "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Admin/BookingController.php"
click node_admin_reports "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Admin/ReportController.php"
click node_chat "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Models/Message.php"
click node_realtime "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Events/BookingStatusUpdated.php"
click node_chatbot "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Services/ChatBotService.php"
click node_suggestions "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Api/SuggestionController.php"
click node_ml_service "https://github.com/aeron-marc/kaayos/blob/main/ml_service/main.py"
click node_market_models "https://github.com/aeron-marc/kaayos/tree/main/kaayos/app/Models"
click node_user_model "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Models/User.php"
click node_services_model "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Models/Service.php"
click node_reviews_model "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Models/Review.php"
click node_expired_command "https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Console/Commands/CancelExpiredBookings.php"

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_discovery_search,node_public_profiles,node_geo_support,node_visitor,node_browser toneBlue
class node_booking_client,node_booking_lifecycle,node_worker_dashboard,node_worker_tools,node_geo_travel,node_expired_command toneAmber
class node_auth,node_verification,node_admin_ops,node_admin_reports,node_openrouter toneMint
class node_chat,node_realtime,node_chatbot,node_suggestions,node_ml_service,node_worker_actor toneRose
class node_web_routes,node_api_routes,node_market_models,node_user_model,node_services_model,node_reviews_model,node_admin_actor,node_reverb_service toneIndigo
```

## Components

### Worker Discovery

- [Search and map](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/SearchController.php): `kaayos/app/Http/Controllers/SearchController.php`
- [Worker profiles](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Client/WorkerController.php): `kaayos/app/Http/Controllers/Client/WorkerController.php`
- [Local geospatial data](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Support/TuyBarangays.php): `kaayos/app/Support/TuyBarangays.php`

### Booking and Work

- [Client bookings](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Client/ClientController.php): `kaayos/app/Http/Controllers/Client/ClientController.php`
- [Booking lifecycle](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Models/Booking.php): `kaayos/app/Models/Booking.php`
- [Worker job dashboard](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Worker/WorkerDashboardController.php): `kaayos/app/Http/Controllers/Worker/WorkerDashboardController.php`
- [Worker services and schedule](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Worker/WorkerController.php): `kaayos/app/Http/Controllers/Worker/WorkerController.php`
- [Travel and scheduling](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Services/GeoTravelService.php): `kaayos/app/Services/GeoTravelService.php`
- [Expired booking cancellation](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Console/Commands/CancelExpiredBookings.php): `kaayos/app/Console/Commands/CancelExpiredBookings.php`

### Accounts and Operations

- [Authentication and profiles](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Auth/RegisterController.php): `kaayos/app/Http/Controllers/Auth/RegisterController.php`
- [Worker verification](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Admin/VerificationController.php): `kaayos/app/Http/Controllers/Admin/VerificationController.php`
- [Admin operations](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Admin/BookingController.php): `kaayos/app/Http/Controllers/Admin/BookingController.php`
- [Reports and exports](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Admin/ReportController.php): `kaayos/app/Http/Controllers/Admin/ReportController.php`

### Realtime and AI

- [Messaging](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Models/Message.php): `kaayos/app/Models/Message.php`
- [Realtime events](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Events/BookingStatusUpdated.php): `kaayos/app/Events/BookingStatusUpdated.php`
- [AI assistant](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Services/ChatBotService.php): `kaayos/app/Services/ChatBotService.php`
- [Worker suggestions](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Http/Controllers/Api/SuggestionController.php): `kaayos/app/Http/Controllers/Api/SuggestionController.php`
- [Matching microservice](https://github.com/aeron-marc/kaayos/blob/main/ml_service/main.py): `ml_service/main.py`

### Application Core

- [Web routes](https://github.com/aeron-marc/kaayos/blob/main/kaayos/routes/web.php): `kaayos/routes/web.php`
- [API routes](https://github.com/aeron-marc/kaayos/blob/main/kaayos/routes/api.php): `kaayos/routes/api.php`
- [Marketplace records](https://github.com/aeron-marc/kaayos/tree/main/kaayos/app/Models): `kaayos/app/Models`
- [User and worker profile](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Models/User.php): `kaayos/app/Models/User.php`
- [Service catalog](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Models/Service.php): `kaayos/app/Models/Service.php`
- [Reviews and testimonials](https://github.com/aeron-marc/kaayos/blob/main/kaayos/app/Models/Review.php): `kaayos/app/Models/Review.php`

### Other components

- **Client or visitor**
- **Worker**
- **Administrator**
- **Browser client**
- **Laravel Reverb**
- **OpenRouter**

## Connections

- Client or visitor → Web routes: requests pages (evidence: `README.md`)
- Worker → Web routes: manages work (evidence: `README.md`)
- Administrator → Web routes: administers platform (evidence: `README.md`)
- Web routes → Search and map: routes search (evidence: `kaayos/routes/web.php`)
- Web routes → Worker profiles: routes profiles (evidence: `kaayos/routes/web.php`)
- Web routes → Client bookings: routes bookings (evidence: `kaayos/routes/web.php`)
- Web routes → Worker job dashboard: routes worker jobs (evidence: `kaayos/routes/web.php`)
- Web routes → Worker services and schedule: routes worker tools (evidence: `kaayos/routes/web.php`)
- Web routes → Authentication and profiles: routes authentication (evidence: `kaayos/routes/web.php`)
- Web routes → Worker verification: routes verification (evidence: `kaayos/routes/web.php`)
- Web routes → Admin operations: routes admin operations (evidence: `kaayos/routes/web.php`)
- Web routes → Reports and exports: routes reporting (evidence: `kaayos/routes/web.php`)
- Client or visitor → API routes: calls assistant API (evidence: `README.md`)
- API routes → Worker suggestions: routes suggestions
- Search and map → Marketplace records: queries workers (evidence: `kaayos/app/Http/Controllers/SearchController.php`)
- Search and map → Service catalog: filters categories (evidence: `kaayos/app/Http/Controllers/SearchController.php`)
- Search and map → Local geospatial data: uses barangays (evidence: `kaayos/app/Http/Controllers/SearchController.php`)
- Worker profiles → Local geospatial data: uses barangays (evidence: `kaayos/app/Http/Controllers/Client/WorkerController.php`)
- Client bookings → Booking lifecycle: creates bookings (evidence: `kaayos/app/Http/Controllers/Client/ClientController.php`)
- Client bookings → Marketplace records: reads and writes records (evidence: `kaayos/app/Http/Controllers/Client/ClientController.php`)
- Client bookings → Realtime events: broadcasts status (evidence: `kaayos/app/Http/Controllers/Client/ClientController.php`)
- Client bookings → Messaging: posts booking messages (evidence: `kaayos/app/Http/Controllers/Client/ClientController.php`)
- Client bookings → Reviews and testimonials: submits reviews (evidence: `README.md`)
- Worker job dashboard → Booking lifecycle: updates status (evidence: `kaayos/app/Http/Controllers/Worker/WorkerDashboardController.php`)
- Worker job dashboard → Realtime events: broadcasts status (evidence: `kaayos/app/Http/Controllers/Worker/WorkerDashboardController.php`)
- Worker job dashboard → Messaging: posts booking messages (evidence: `kaayos/app/Http/Controllers/Worker/WorkerDashboardController.php`)
- Worker services and schedule → Travel and scheduling: builds routes (evidence: `kaayos/app/Http/Controllers/Worker/WorkerController.php`)
- Worker services and schedule → Marketplace records: reads worker records (evidence: `kaayos/app/Http/Controllers/Worker/WorkerController.php`)
- Client bookings → Travel and scheduling: checks feasibility (evidence: `kaayos/app/Http/Controllers/Client/ClientController.php`)
- Expired booking cancellation → Booking lifecycle: cancels stale bookings (evidence: `README.md`)
- Authentication and profiles → User and worker profile: creates accounts
- Worker verification → User and worker profile: verifies workers (evidence: `README.md`)
- Admin operations → Marketplace records: manages marketplace data (evidence: `README.md`)
- Reports and exports → Marketplace records: reports on activity (evidence: `kaayos/app/Http/Controllers/Admin/ReportController.php`)
- Reports and exports → Reviews and testimonials: includes review reports (evidence: `README.md`)
- Worker suggestions → AI assistant: requests assistant reply (evidence: `kaayos/app/Http/Controllers/Api/SuggestionController.php`)
- Worker suggestions → User and worker profile: finds matching workers (evidence: `kaayos/app/Http/Controllers/Api/SuggestionController.php`)
- Worker suggestions → Matching microservice: requests matching
- AI assistant → OpenRouter: calls AI provider (evidence: `README.md`)
- Browser client → Laravel Reverb: receives live updates (evidence: `README.md`)
- Realtime events → Laravel Reverb: publishes events (evidence: `README.md`)
- Marketplace records → User and worker profile: stores domain records (evidence: `kaayos/app/Models/Booking.php`)
- Booking lifecycle → Marketplace records: persists booking state (evidence: `README.md`)
- Service catalog → Marketplace records: stores catalog data (evidence: `kaayos/app/Models/ServiceCategory.php`)
- Reviews and testimonials → Marketplace records: stores feedback (evidence: `kaayos/app/Models/User.php`)
