# 15. Admin Portal

## Admin Roles

Binary admin model. `is_admin = 1` on the `users` table grants full admin access. First registered user is automatically admin.

No intermediate roles, no per-feature permissions, no delegation.

## Admin Routes

All admin routes require `authenticateAdmin` middleware (JWT + `isAdmin` check).

| Route Group | Purpose |
|-------------|---------|
| `/api/admin/users` | User CRUD |
| `/api/admin/ai-provider/*` | AI provider configuration |
| `/api/admin/bedrock/*` | AWS Bedrock management |
| `/api/admin/cloud-connections/*` | Cloud drive connections |
| `/api/admin/cloud-mounts/*` | Cloud mount points |
| `/api/admin/hook-*-report` | Analytics reports |
| `/api/admin/output-styles/*` | Output style management |
| `/api/admin/refresh-stats` | Analytics refresh |
| `/api/admin/quality-analysis` | Quality signal processing |
| `/api/admin/skill-usage-report` | Skill analytics |

## Admin Capabilities

### User Management

| Action | Endpoint | Details |
|--------|----------|---------|
| List users | GET `/api/admin/users` | All users with metadata |
| Create user | POST `/api/admin/users` | Username, password, admin flag |
| Update user | PATCH `/api/admin/users/:id` | Change role, reset password |
| Delete user | DELETE `/api/admin/users/:id` | CASCADE deletes related records |
| Send welcome email | POST `/api/admin/users/:id/welcome-email` | Via Postmark template |

### AI Provider Management

| Action | Endpoint | Details |
|--------|----------|---------|
| View provider status | GET `/api/admin/ai-provider/status` | Active provider, health |
| List available models | GET `/api/admin/ai-provider/models` | Claude and Bedrock models |
| Activate provider | POST `/api/admin/ai-provider/activate` | Switch between Claude/Bedrock |
| Configure Bedrock | POST `/api/admin/bedrock/configure` | AWS credentials, region |
| Test Bedrock | POST `/api/admin/bedrock/test` | Validate connection |
| Switch model | POST `/api/admin/bedrock/switch-model` | Change active model |
| Toggle 1M context | POST `/api/admin/bedrock/context-mode` | Enable/disable with audit |
| Remove Bedrock | DELETE `/api/admin/bedrock` | Clear configuration |

### Analytics & Reporting

| Report | Endpoint | Data Source |
|--------|----------|-------------|
| Hook usage | GET `/api/admin/hook-usage-report` | `hook_usage_rollups` |
| Session report | GET `/api/admin/hook-session-report` | `hook_sessions` |
| Command report | GET `/api/admin/hook-command-report` | `hook_command_rollups` |
| Context report | GET `/api/admin/hook-context-report` | Hook events analysis |
| Timeseries | GET `/api/admin/hook-timeseries-report` | Rollups by time bucket |
| User activity | GET `/api/admin/hook-user-activity-report` | Per-user analytics |
| Skill usage | GET `/api/admin/skill-usage-report` | Skill execution stats |

**Stats refresh:** POST `/api/admin/refresh-stats` triggers `statsRefreshWorker.js` (forked process) to process hook event JSONL files into rollup tables.

### Output Styles

| Action | Endpoint | Details |
|--------|----------|---------|
| List styles | GET `/api/admin/output-styles` | All output style definitions |
| Get style | GET `/api/admin/output-styles/:id` | Single style details |
| Create style | POST `/api/admin/output-styles` | Name, content, metadata |
| Update style | PUT `/api/admin/output-styles/:id` | Modify existing style |
| Delete style | DELETE `/api/admin/output-styles/:id` | Remove style |

Output styles modify Claude's response format via system prompt injection or post-processing.

### Cloud Drive Administration

| Action | Endpoint | Details |
|--------|----------|---------|
| List connections | GET `/api/admin/cloud-connections` | All cloud provider connections |
| Create connection | POST `/api/admin/cloud-connections` | Provider type, credentials |
| Authorize | POST `/api/admin/cloud-connections/:id/authorize` | Start OAuth flow |
| Delete connection | DELETE `/api/admin/cloud-connections/:id` | Remove connection |
| List mounts | GET `/api/admin/cloud-mounts` | All mount points |
| Create mount | POST `/api/admin/cloud-mounts` | Path, access mode, VFS profile |
| Remount | POST `/api/admin/cloud-mounts/:id/remount` | Re-establish mount |
| Delete mount | DELETE `/api/admin/cloud-mounts/:id` | Remove mount |

### System Health Dashboard

Available in admin settings (General tab):

| Metric | Source | Alert Threshold |
|--------|--------|----------------|
| Disk usage | Filesystem stats | Green <70%, Yellow 70-85%, Red >85% |
| CPU load | System metrics | TBD |
| Memory usage | Process metrics | Configurable thresholds |
| Database health | `PRAGMA integrity_check` | Pass/fail |
| Claude API | `/api/setup/claude-status` | Connected/disconnected |
| WebSocket | Connection count | Active/inactive |

## Audit Logging

| Audit Table | What It Records |
|-------------|----------------|
| `hook_events` | All Claude Code tool invocations |
| `hook_tool_execs` | Tool execution details (command, duration, success) |
| `hook_sessions` | Session lifecycle (start, end, reason) |
| `hook_file_accesses` | File read/write operations |
| `execution_history` | Scheduled prompt execution results |
| `executions` | All execution types (schedule, meeting, API) |
| `api_key_usage` | External API key activity |
| `usage_events` | Token consumption and cost per exchange |
| `response_quality_signals` | Response quality metrics |
| `feedback_events` | User thumbs up/down feedback |
| `stats_refresh_log` | Analytics refresh history |
| `bedrock_context_audit` | 1M context toggle acknowledgments |
| `prompt_versions` | CLAUDE.md and prompt change history |

## Admin UI Components

| Component | File | Purpose |
|-----------|------|---------|
| `AIProviderSelector` | `admin/AIProviderSelector.jsx` | Provider selection card |
| `BedrockConfigModal` | `admin/BedrockConfigModal.jsx` | Bedrock setup dialog |
| `ClaudeConfigModal` | `admin/ClaudeConfigModal.jsx` | Claude API key dialog |
| `OutputStyleModal` | `admin/OutputStyleModal.jsx` | Style editor dialog |
| `OutputStylesManager` | `admin/OutputStylesManager.jsx` | Style list management |
| `ProviderCard` | `admin/ProviderCard.jsx` | Provider status card |
| `ReportingPage` | `ReportingPage.jsx` | Analytics dashboard |