# Developer Experience Dashboard & Console
## Sprint DX003 Architecture & Reference Guide

---

## Overview

Sprint DX003 transforms the Developer Console into a production-grade **Developer Experience Dashboard**. It introduces real-time system metrics, automated environment diagnostics, a multi-tab log center, application specifications, quick action shortcuts, and role/environment access security.

**Core Principles:**
1. **Source of Truth:** MySQL remains the sole runtime database for application business logic.
2. **Read-Only Cloud Mirror:** Supabase PostgreSQL is strictly a cloud mirror / backup target.
3. **Manual Synchronization:** Synchronization operations are manual-only (DX002B engine).
4. **Environment Guard:** Developer Console access is protected by `DEVELOPER_MODE=true` in `.env` and `DeveloperMiddleware`.

---

## Developer Console Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                      Developer Console Portal (/app/developer/*)            │
├─────────────────────────────────────────────────────────────────────────────┤
│ Middleware Gate: AuthMiddleware → RoleMiddleware → DeveloperMiddleware      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  [Dashboard]          [Database Overview]      [Schema Documentation]       │
│  /app/developer       /app/developer/database  /app/developer/schema       │
│                                                                             │
│  [Supabase Inspector] [DB Inspector]           [Type Mapping Reference]     │
│  /app/developer/sb    /app/developer/inspector /app/developer/mapping     │
│                                                                             │
│  [Synchronization]    [Sync History Log]       [System Health]             │
│  /app/developer/sync  /app/developer/sync/log  /app/developer/health       │
│                                                                             │
│  [Log Center]         [Application Info]                                    │
│  /app/developer/logs  /app/developer/info                                   │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Developer Dashboard Sections

### 1. Developer Summary Panel (Feature 10)
High-level operational overview summarizing:
- **App Status:** Operational & Environment (`LOCAL` / `STAGING` / `PRODUCTION`)
- **Database Status:** MySQL PDO connectivity & total tables
- **Mirror Status:** Supabase configuration state
- **Documentation Status:** Baseline schema version
- **Sync Status:** Current execution mode (`management_api` or `sql_export`)
- **Overall System Health:** Calculated health state (`Healthy` | `Warning` | `Error`)

### 2. Quick Actions Bar (Feature 9)
Direct action triggers for key developer utilities:
- **Test Supabase Connection:** Live AJAX health check
- **Compare Schema:** Launch schema diff engine
- **Verify Mirror:** Run mirror integrity check
- **Open Sync Center:** Direct access to manual push/dry-run tool
- **Open Database Inspector:** Side-by-side MySQL vs Supabase inspector
- **Open Mapping Reference:** MySQL → PostgreSQL type translation reference

### 3. System Metrics Grid (Feature 1)
12 real-time metric cards:
1. Application Version (`1.0.0`)
2. Environment (`LOCAL`)
3. PHP Version (`8.2.x`) & SAPI
4. MySQL / MariaDB Version
5. Supabase Configuration Status
6. Mirror Status
7. Database Tables & Columns Count
8. Total Registered Routes
9. Total Application Modules
10. Storage Disk Usage (`storage/`)
11. Last Synchronization Timestamp
12. System Health Badge

---

## System Health Diagnostics (Feature 2)

The `SystemHealthService` evaluates 9 core environment checks:

| Check | Key | Category | Success Criteria |
|-------|-----|----------|------------------|
| Database Connection | `database_connection` | Infrastructure | Active MySQL PDO connection |
| Supabase Connection | `supabase_connection` | Cloud Mirror | HTTP 200/401 response from Supabase REST API |
| Storage Permissions | `storage_permissions` | File System | `storage/` directory is writeable |
| Log Directory | `storage_logs` | File System | `storage/logs/` exists & writeable |
| Cache Directory | `storage_cache` | File System | `storage/cache/` exists & writeable |
| PHP Extensions | `php_extensions` | Environment | `pdo`, `pdo_mysql`, `curl`, `json`, `mbstring`, `openssl`, `fileinfo` loaded |
| PHP Memory Limit | `php_memory_limit` | Resource Limits | `memory_limit` >= 128M |
| Upload & Post Limit | `upload_limits` | Resource Limits | `upload_max_filesize` & `post_max_size` |
| Execution Time Limit | `execution_time_limit` | Resource Limits | `max_execution_time` >= 30s or unlimited (0) |

Each check displays:
- **Status Badge:** `Healthy` (green), `Warning` (amber), `Error` (red)
- **Current Value:** Live measured value
- **Recommendation:** Actionable fix instructions when unhealthy or warning

---

## Log Center (Feature 4)

Centralized viewer for all system logs (`/app/developer/logs`):

- **Sync Logs:** Manual push, dry run, and verification history (stored in `storage/developer/sync_log.json`).
- **Application Logs:** Application runtime logs from `storage/logs/app.log`.
- **PHP Error Logs:** PHP runtime error logs from `storage/logs/php_errors.log`.
- **All Activity Feed:** Combined chronological stream, newest first.

**Actions Available:**
- **Refresh Stream:** Reload log feed
- **Clear Log:** Truncates specified log file (requires user confirmation)
- **Download Log:** Triggers secure browser download of `.log` / `.json` file

---

## Security Model & Developer Mode (Feature 12)

Access to `/app/developer/*` routes is governed by a 3-layer security pipeline:

```
Request → AuthMiddleware (Valid Session) → RoleMiddleware (super_admin) → DeveloperMiddleware (DEVELOPER_MODE=true)
```

1. **`DEVELOPER_MODE=true` in `.env`:**
   Controls whether the Developer Console portal is active. If set to `false`, `DeveloperMiddleware` blocks all requests with a `403 Forbidden` error and logs a security warning.
2. **Credential Masking:**
   `SUPABASE_SERVICE_ROLE_KEY` and `SUPABASE_ACCESS_TOKEN` are kept server-side only and are **never** rendered in views or returned in API responses.

---

## Validation & Sprints Summary

| Sprint | Scope | Key Capabilities |
|--------|-------|------------------|
| **DX001** | Database Documentation & Developer Console Base | 43 table markdown docs, MySQL Inspector, Schema status |
| **DX002A** | Supabase Mirror Foundation | Credentials config, connection test, masked API keys |
| **DX002B** | Synchronization Engine | Manual Push, DDL Generator, Dry Run, Verification, Sync Log |
| **DX003** | Developer Experience Dashboard | System Health Suite, Log Center, App Info, Dashboard Metrics, `DEVELOPER_MODE` Guard |