eventify_command_center/API_AND_DB_SPEC.md

# Eventify Command Center - API & Database Specification

This document outlines the required API endpoints and Database schema to support the current features of the Eventify Command Center (Admin Panel).

---

## 🏗 Database Schema

### 1. User Management (RBAC)

**`admin_users`** (Internal Staff)
| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Primary Key |
| `email` | VARCHAR | Unique email |
| `password_hash` | VARCHAR | Hashed password |
| `full_name` | VARCHAR | Display name |
| `role_id` | UUID | FK to `roles` |
| `status` | ENUM | 'Active', 'Inactive' |
| `last_active_at` | TIMESTAMP | Last login time |

**`roles`**
| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Primary Key |
| `name` | VARCHAR | e.g. "Super Admin", "Content Moderator" |
| `description` | TEXT | |
| `is_system` | BOOLEAN | If true, cannot be deleted |

**`permissions`**
| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | VARCHAR | Primary Key (e.g. `manage_partners`) |
| `name` | VARCHAR | Human readable name |
| `group` | VARCHAR | e.g. "Finance", "Users" |

**`role_permissions`** (Junction Table)
| Column | Type | Description |
| :--- | :--- | :--- |
| `role_id` | UUID | FK to `roles` |
| `permission_id` | VARCHAR | FK to `permissions` |

---

### 2. Partner Management

**`partners`** (Organizations)
| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Primary Key |
| `name` | VARCHAR | Business Name |
| `type` | ENUM | 'Venue', 'Promoter', 'Sponsor', 'Vendor' |
| `status` | ENUM | 'Active', 'Invited', 'Suspended' |
| `logo_url` | VARCHAR | |
| `verification_status` | ENUM | 'Pending', 'Verified', 'Rejected' |
| `total_revenue` | DECIMAL | Cache field for performance |
| `open_balance` | DECIMAL | Amount owed to/by partner |
| `joined_at` | TIMESTAMP | |

**`partner_contacts`**
| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Primary Key |
| `partner_id` | UUID | FK to `partners` |
| `name` | VARCHAR | |
| `email` | VARCHAR | |
| `phone` | VARCHAR | |
| `is_primary` | BOOLEAN | |

**`partner_documents`** (KYC)
| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Primary Key |
| `partner_id` | UUID | FK to `partners` |
| `type` | ENUM | 'Company_Reg', 'PAN', 'Cheque', 'Other' |
| `file_url` | VARCHAR | S3/Blob URL |
| `status` | ENUM | 'Pending', 'Verified', 'Rejected' |
| `uploaded_at` | TIMESTAMP | |
| `verified_at` | TIMESTAMP | |

---

### 3. End Users (B2C)

**`end_users`**
| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Primary Key |
| `email` | VARCHAR | |
| `phone` | VARCHAR | |
| `full_name` | VARCHAR | |
| `status` | ENUM | 'Active', 'Banned' |
| `total_spent` | DECIMAL | Lifetime value |
| `created_at` | TIMESTAMP | |

---

### 4. Operations & Logs

**`audit_logs`**
| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Primary Key |
| `actor_id` | UUID | FK to `admin_users` |
| `action` | VARCHAR | e.g. "APPROVED_KYC" |
| `target_resource` | VARCHAR | e.g. "partner_123" |
| `details` | JSONB | Metadata about changes |
| `created_at` | TIMESTAMP | |

**`notifications`**
| Column | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Primary Key |
| `recipient_id` | UUID | FK to `admin_users` |
| `type` | ENUM | 'Critical', 'Info', 'Success' |
| `title` | VARCHAR | |
| `message` | TEXT | |
| `is_read` | BOOLEAN | |
| `created_at` | TIMESTAMP | |

---

## 🔌 API Endpoints

### Authentication
- `POST /api/v1/auth/login` - Admin login (returns JWT)
- `POST /api/v1/auth/logout` - Invalidate session
- `GET /api/v1/auth/me` - Get current admin profile & permissions

### Dashboard
- `GET /api/v1/dashboard/metrics` - Aggregate stats (revenue, active partners, etc.)
- `GET /api/v1/dashboard/revenue-chart` - Data for the main revenue graph
- `GET /api/v1/dashboard/activity` - Recent system activity feed

### Partner Management
- `GET /api/v1/partners` - List partners (Supports filtering by status, type, search)
- `POST /api/v1/partners` - Invite/Create new partner
- `GET /api/v1/partners/:id` - Get full partner profile
- `GET /api/v1/partners/:id/documents` - List KYC documents
- `PATCH /api/v1/partners/:id/status` - Suspend/Activate partner
- `POST /api/v1/partners/:id/kyc/review` - Approve/Reject specific documents

### User Management (Command Center)
- **Internal Team**
    - `GET /api/v1/admin/users` - List internal staff
    - `POST /api/v1/admin/users` - Create staff account
    - `PATCH /api/v1/admin/users/:id/role` - Assign role
    - `DELETE /api/v1/admin/users/:id` - Revoke access
- **Roles & Permissions**
    - `GET /api/v1/admin/roles` - List available roles
    - `PUT /api/v1/admin/roles/:id/permissions` - Update permission matrix for a role
- **End Users**
    - `GET /api/v1/users` - List B2C users
    - `POST /api/v1/users/:id/ban` - Ban a user
    - `POST /api/v1/users/:id/reset-2fa` - Reset 2FA

### Financials (Placeholder)
- `GET /api/v1/financials/entries` - List ledger entries
- `POST /api/v1/financials/payouts` - Trigger batch payouts