# VisoAdmin — Feature Specifications ## Platform Overview **VisoAdmin** is the Laravel-powered **back-office / control plane** for the OOTBO event-marketplace platform. It is the operational cockpit used by the OOTBO ops team — **Relationship Managers (RMs)**, **Coordinators**, **Customer Care**, **Business Development**, **Analytics Viewers**, **Applications Managers**, and **Superadmins** — to onboard, moderate, and assist the two-sided marketplace that the public-facing apps (Client + Vendor) expose to end users. VisoAdmin does **not** itself host clients or vendors. It writes into the same MySQL database that powers the public APIs (`OotboAPI/VisoAPI`) and reads/writes the same chat/notification streams that the apps interact with. | Aspect | Detail | |--------|--------| | **Framework** | Laravel 8.75 (PHP 7.3 / 8.0) | | **UI** | Server-rendered Blade + AdminLTE + jQuery + DataTables | | **Auth** | Sessions (`admins` table) + Sanctum scaffolding | | **Persona** | OOTBO ops team (8 distinct internal roles) | | **Domain DB** | Shared MySQL (`ootbomvp`) — same tables as `OotboAPI/VisoAPI` | | **Realtime** | HTTP push to `Viso-Chat` socket bridge (`SOCKET_URL` from `.env`) | | **Storage** | Local + AWS S3 for vendor images | --- ## Place in the OOTBO Ecosystem ``` ┌──────────────────────────────────────────────────────────────────────┐ │ OOTBO ECOSYSTEM │ │ │ │ ┌────────────────┐ ┌────────────────┐ │ │ │ Client App │ │ Vendor App │ (OotboApps — Ionic) │ │ │ (Ionic) │ │ (Ionic) │ │ │ └────────┬───────┘ └────────┬───────┘ │ │ │ │ │ │ └──────────┬─────────┘ │ │ ▼ │ │ ┌────────────────────┐ ┌──────────────────┐ │ │ │ OotboAPI │◀───────▶│ Viso-Chat │ │ │ │ (Laravel PHP) │ │ (Socket / WS) │ │ │ └─────────┬──────────┘ └────────┬─────────┘ │ │ │ │ │ │ ▼ shared MySQL DB │ HTTP push │ │ ┌────────────────────┐ │ │ │ │ │ │ │ │ │ ootbomvp DB │ │ │ │ │ (events, users, │ │ │ │ │ conversation, │ │ │ │ │ chat, …) │ │ │ │ │ │ │ │ │ └─────────┬──────────┘ │ │ │ ▲ │ │ │ │ direct DB R/W │ │ │ ┌─────────┴──────────┐ │ │ │ │ VisoAdmin │──────────────────┘ │ │ │ (Laravel) │ /notification POST emits │ │ │ ↑ THIS REPO ↑ │ │ │ └────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────────────┘ ``` VisoAdmin sits **alongside** OotboAPI on the same database. It is the *only* surface where ops team members log in. There is no overlap between admin users (`admins` table) and end users (`users` table) — they are separate auth realms. --- ## Folder Structure ``` docs/features/ ├── 00-overview/ │ ├── README.md ← You are here │ ├── cross-app-interactions.md ← How VisoAdmin talks to API / DB / Socket │ └── regression-matrix.md ← Feature coupling & risk │ ├── 01-admin-authentication/ ← Sessions, login, password reset ├── 02-admin-rbac/ ← Roles, permissions, menu gating, superadmin ├── 03-admin-user-management/ ← CRUD ops on `admins` table (the ops team) ├── 04-client-management/ ← Read-only oversight of end-user clients ├── 05-vendor-management/ ← Vendor CRUD + service/location bindings + delete cascade ├── 06-event-oversight/ ← List / inspect / edit events created by clients ├── 07-coordinator-console/ ← Coordinator workbench (lookup events by human ID) ├── 08-rm-requests/ ← RM intake queue (incoming `client_rm_requests`) ├── 09-rm-create-event/ ← RM-led booking lifecycle (create event for a client) ├── 10-dashboard-critical-events/ ← Upcoming events with zero vendor quotes ├── 11-analytics/ ← KPI cards + bar/pie chart explorer ├── 12-master-data-locations/ ← Countries / States / Cities CRUD ├── 13-master-data-services/ ← Services catalog CRUD ├── 14-faq-management/ ← Client / Vendor FAQ read-only viewer ├── 15-app-settings/ ← Contact email/phone, app-store links, telecmi ├── 16-notifications-admin/ ← Admin-targeted notifications panel + badge ├── 17-notification-settings/ ← Vendor email/phone routing for outbound emails ├── 18-user-reports/ ← Abuse reports raised on the apps (client→vendor) ├── 19-suggestions/ ← App-suggestion inbox from end users ├── 20-user-activity-log/ ← Audit trail of admin actions │ └── work-flows/ ├── rm-led-booking.md ← RM intake → create event → publish lead → quotes ├── vendor-lifecycle.md ← Vendor create → services bound → delete cascade ├── ops-moderation.md ← Reports & suggestions intake → action └── notification-fanout.md ← In-app + socket + email notification flow ``` --- ## Feature Map ``` ┌──────────────────────────────────────────────────────────────────────┐ │ VISO-ADMIN │ ├──────────────────────────────────────────────────────────────────────┤ │ │ │ AUTH & GOVERNANCE │ │ 01 Authentication ──▶ 02 RBAC ──▶ 03 Admin User Mgmt │ │ │ │ OPS OVERSIGHT (READ-MOSTLY) │ │ 04 Client Mgmt 05 Vendor Mgmt 06 Event Oversight │ │ └──── 10 Critical Events (dashboard alert) ────┘ │ │ │ │ RM / COORDINATOR WORKBENCH │ │ 07 Coordinator Console 08 RM Requests 09 RM Create Event │ │ │ │ ANALYTICS │ │ 11 Analytics (KPI + bar + pie) │ │ │ │ MASTER DATA │ │ 12 Locations 13 Services │ │ │ │ CONTENT & CONFIG │ │ 14 FAQs 15 App Settings │ │ │ │ COMMS │ │ 16 Notifications (admin inbox) │ │ 17 Notification Settings (outbound vendor email routing) │ │ │ │ TRUST & SAFETY │ │ 18 User Reports 19 Suggestions 20 User Activity Log │ │ │ └──────────────────────────────────────────────────────────────────────┘ ``` --- ## Personas ### Superadmin (`admins.superadmin = 1`) - **Goal**: Unrestricted access. Sees every menu, bypasses all permission checks (`UserPermission` middleware). - **Typical activity**: Onboarding new admin users, granting role permissions, fixing data. ### Project Manager / Applications Manager (role 1 / 5) - **Goal**: Run the platform day-to-day. - **Permissions**: Event-level details, user-level data, app settings. ### Coordinator — Host & Partner (role 2 / 3, `superadmin = 2`) - **Goal**: Help clients & vendors connect for individual events. - **Permissions**: Coordinator menu only (`coordinatorPermission() === [7]`). - **Distinct because**: `superadmin = 2` is a SECOND privileged tier — auto-routes to `/coordinator` after login (see `WelcomeController`). ### Customer Care (role 4) - **Goal**: Triage reports & suggestions. - **Permissions**: Reporting, possibly user data. ### Analytics Viewer (role 6) - **Goal**: Read-only dashboards. Cannot mutate. ### Business Development (role 7) - **Goal**: Onboarding-style ops. Defined in `roles()` helper but not heavily exercised in code. ### Relationship Manager — RM (role 8) - **Goal**: Convert client RM requests into events, push leads to vendors. - **Permissions**: RM menu only (`8`). RM is scoped to a country (`admins.country_code`) — they only see requests from their country (see `RmController::getRmData()`). > The 8 internal roles are defined in `app/Helpers/GlobalMethods.php :: roles()`. --- ## Status Legend | Status | Meaning | |--------|---------| | **Live** | Feature is fully implemented and in production use | | **MVP** | Implemented but with rough edges / hardcoded behaviour | | **Partial** | Some sub-flows missing or commented out in code | | **Planned** | Defined in code skeleton but not functional | --- ## Feature Status Summary | # | Feature | Status | Spec | |---|---------|--------|------| | 01 | Admin Authentication | Live | [spec](../01-admin-authentication/spec.md) | | 02 | Admin RBAC | Live | [spec](../02-admin-rbac/spec.md) | | 03 | Admin User Management | Live | [spec](../03-admin-user-management/spec.md) | | 04 | Client Management | Live | [spec](../04-client-management/spec.md) | | 05 | Vendor Management | Live | [spec](../05-vendor-management/spec.md) | | 06 | Event Oversight | Live | [spec](../06-event-oversight/spec.md) | | 07 | Coordinator Console | Live | [spec](../07-coordinator-console/spec.md) | | 08 | RM Requests | Live | [spec](../08-rm-requests/spec.md) | | 09 | RM Create Event | Live | [spec](../09-rm-create-event/spec.md) | | 10 | Critical Events (Dashboard) | Live | [spec](../10-dashboard-critical-events/spec.md) | | 11 | Analytics | Live | [spec](../11-analytics/spec.md) | | 12 | Master Data — Locations | Live | [spec](../12-master-data-locations/spec.md) | | 13 | Master Data — Services | Live | [spec](../13-master-data-services/spec.md) | | 14 | FAQ Management | Partial | [spec](../14-faq-management/spec.md) | | 15 | App Settings | Live | [spec](../15-app-settings/spec.md) | | 16 | Notifications (Admin Inbox) | Partial | [spec](../16-notifications-admin/spec.md) | | 17 | Notification Settings | Live | [spec](../17-notification-settings/spec.md) | | 18 | User Reports | Live | [spec](../18-user-reports/spec.md) | | 19 | Suggestions | Live | [spec](../19-suggestions/spec.md) | | 20 | User Activity Log | Live | [spec](../20-user-activity-log/spec.md) | --- ## How to Read These Specs Each feature folder contains a `spec.md` with these sections (in this order): 1. **Overview** — what the feature does, status 2. **User Stories** — table: ID | As a | I want to | So that 3. **Screens & Flows** — ASCII diagram + routes/actions table 4. **Data Model** — entities, fields, code blocks 5. **Validations & Business Rules** — table: Rule | Detail 6. **API Endpoints** — method + path + auth + request/response shape + consumers (here: outbound HTTP, since VisoAdmin's primary surface is its own HTML routes; for outbound HTTP calls into Viso-Chat and OotboAPI see [cross-app-interactions.md](./cross-app-interactions.md)) 7. **Upstream Impact** — what feeds INTO this feature 8. **Downstream Impact** — what this feeds INTO 9. **Impact of Changes** — table: If you change X | Risk to Y | Level | Type --- ## Key Architectural Notes for New Engineers 1. **Two `User` models point at two different tables.** `App\Models\User` → `admins`. `App\Models\Users` (note plural) → `users`. The `Authenticatable` (`User`) is the admin. Confusion here is the #1 onboarding trap. 2. **`superadmin` has THREE values**: `0` = regular admin (uses role+permission), `1` = full superadmin (bypasses everything), `2` = coordinator (bypasses to coordinator menu via `Coordinator` middleware). 3. **Permissions are stored TWICE**: per-user (`admins.permission`, comma-separated) and per-role (`role_permissions.permission`, comma-separated). `User::getHaspermissionAttribute()` reads the role one. 4. **No service layer for most features.** Controllers query DB directly with `DB::raw(...)` and string-concatenated SQL. SQL injection risk is real if you accept user input into these places — see [regression-matrix.md](./regression-matrix.md). 5. **No CSRF for some POST routes** — controllers rely on session auth. 6. **`api.php` is nearly empty.** This is *not* a REST API project. All routes are `web.php` Blade pages + AJAX endpoints inside the same session-auth realm. 7. **UAE-only**: `RmController::createEventForm()` hard-pins to `Countries::where('name','United Arab Emirates')`. Other countries exist in master data but are not used by RM flows.