mic-check/docs/admin/01-admin-site_plan.md

# MicCheck Admin Site Plan

## Overview

Build a fully functional VueJS 3 + Vuetify 3 + TypeScript single-page admin application for the MicCheck feature flag platform. The site manages the complete lifecycle of feature flags across the Organization → Project → Environment hierarchy exposed by the MicCheck API.

---

## Architecture Decisions

- **State Management**: Pinia (replaces Vuex; first-class Vue 3 support)
- **HTTP Client**: Axios with request/response interceptors for auth token injection and 401 refresh handling
- **Component Library**: Vuetify 3 (already configured)
- **Router**: Vue Router 4 (already configured)
- **Testing**: Jest + Vue Test Utils (already configured)
- **Code Style**: Composition API (`<script setup>`), TypeScript throughout

### Context Model

The app operates in a three-level context:
1. **Organization** — selected at login/org-switcher; stored globally
2. **Project** — selected via project switcher in nav; stored globally
3. **Environment** — selected via environment dropdown in nav; stored globally

All feature, segment, identity, and audit views are scoped to the current org/project/environment context.

---

## Chunk 1: Foundation — API Client, Auth & Stores

### Goals
Set up the core infrastructure that all subsequent chunks depend on: typed API client, Pinia stores, authentication flows, and route guards.

### Tasks

#### 1.1 Install Pinia
- Add `pinia` to `package.json`
- Register Pinia in `main.ts`

#### 1.2 Typed API Client (`src/api/`)
Create an `ApiClient` class using Axios:
- Base URL configured from environment variable (`VITE_API_BASE_URL` or webpack `DefinePlugin`)
- Request interceptor: inject `Authorization: Bearer <token>` for admin calls, or `X-Environment-Key` for flags API calls
- Response interceptor: on 401, attempt token refresh via `POST /api/v1/auth/refresh`; on refresh failure, redirect to `/login`
- Typed methods for each API domain (auth, organizations, projects, environments, features, featureStates, segments, tags, auditLogs, webhooks, identities, apiKeys)
- All responses typed using TypeScript interfaces mirroring the API response models

#### 1.3 Auth Store (`src/stores/auth.ts`)
Pinia store with:
- State: `user`, `accessToken`, `refreshToken`, `expiresAt`, `isAuthenticated`
- Actions: `login(email, password)`, `register(...)`, `logout()`, `refreshToken()`, `loadFromStorage()`
- Persist tokens to `localStorage`; restore on app init

#### 1.4 Context Store (`src/stores/context.ts`)
Pinia store with:
- State: `currentOrganization`, `currentProject`, `currentEnvironment`
- Actions: `setOrganization(org)`, `setProject(project)`, `setEnvironment(env)`
- Persist selections to `localStorage`

#### 1.5 Login & Register Views
- `LoginView.vue`: email/password form → calls auth store `login()` → redirects to dashboard
- `RegisterView.vue`: email, password, first name, last name, organization name → calls `register()` → redirects to dashboard
- Both views displayed without the main `AppLayout` (full-page centered card)
- Client-side validation with Vuetify's built-in form validation

#### 1.6 Route Guards
In `router/index.ts`:
- `beforeEach` guard: if route requires auth and user is not authenticated, redirect to `/login`
- If authenticated user navigates to `/login`, redirect to `/`
- Mark public routes (`/login`, `/register`) with `meta: { public: true }`

#### 1.7 Unit Tests
- Auth store: login success, login failure, token refresh, logout
- API client: interceptors, token injection, refresh on 401

---

## Chunk 2: Navigation & Context Selectors

### Goals
Build the main app shell with a context-aware navigation bar that allows switching between organizations, projects, and environments.

### Tasks

#### 2.1 Update `AppLayout.vue`
- Left sidebar (Vuetify `v-navigation-drawer`) with:
  - MicCheck logo at top
  - Organization selector (dropdown showing org name)
  - Project selector (dropdown scoped to selected org)
  - Environment pill/tab selector (shows all environments for current project)
  - Navigation links: Features, Segments, Identities, Audit Logs
  - Bottom: Settings link
- Top `v-app-bar` with:
  - Page title / breadcrumb
  - User name and avatar icon → `/profile`
  - Gear icon → `/settings`

#### 2.2 Organization Selector Component (`src/components/OrgSelector.vue`)
- Fetches `GET /api/v1/organisations` on mount
- Displays current org name as button; opens dropdown to switch
- On select: updates context store, resets project and environment selection

#### 2.3 Project Selector Component (`src/components/ProjectSelector.vue`)
- Fetches `GET /api/v1/projects?organizationId=` when org changes
- Displays current project name; opens dropdown to switch
- On select: updates context store, resets environment selection

#### 2.4 Environment Tab Bar Component (`src/components/EnvironmentTabBar.vue`)
- Fetches `GET /api/v1/environments?projectId=` when project changes
- Displays environments as tabs (Vuetify `v-tabs`)
- Highlights selected environment; updates context store on click
- "Add Environment" button at the end of the tabs

#### 2.5 Empty States
- If no organization: prompt to create one
- If no project: prompt to create first project
- If no environment: prompt to create first environment

#### 2.6 Update Router
Add routes:
```
/login          → LoginView (public)
/register       → RegisterView (public)
/               → DashboardView (auth required)
/features       → FeaturesView (auth required)
/segments       → SegmentsView (auth required)
/identities     → IdentitiesView (auth required)
/audit-logs     → AuditLogsView (auth required)
/settings       → SettingsView (auth required)
/profile        → ProfileView (auth required)
```

#### 2.7 Dashboard View
Simple landing page showing:
- Selected org/project/environment summary cards
- Quick stats: number of features, segments, enabled flags in current environment
- Links to main sections

#### 2.8 Unit Tests
- OrgSelector: loads orgs, emits selection
- ProjectSelector: loads projects on org change
- EnvironmentTabBar: loads envs, highlights selected, emits selection
- Route guard: unauthenticated redirect, authenticated bypass

---

## Chunk 3: Feature Flags Management

### Goals
Full CRUD for features (project-level) and their per-environment states (toggle on/off, set value).

### Tasks

#### 3.1 Features List View (`FeaturesView.vue`)
- Table/data-grid using Vuetify `v-data-table-server` with server-side pagination
- Columns: Name, Type (STANDARD/MULTIVARIATE), Description, Default Enabled, Created At, Actions
- Per-row toggle switch for the current environment's feature state (`PATCH /api/v1/environments/{apiKey}/featurestates/{id}`)
- Search/filter by name
- "Create Feature" button → opens dialog

#### 3.2 Feature Create/Edit Dialog (`src/components/features/FeatureDialog.vue`)
- Fields:
  - **Name** (text input; validates `^[a-zA-Z0-9_-]+$`, max 150)
  - **Type** (select: STANDARD / MULTIVARIATE)
  - **Initial Value** (text area; shown for MULTIVARIATE; max 20,000 chars)
  - **Description** (text area; optional)
- On create: `POST /api/v1/projects/{projectId}/features`
- On edit: `PUT /api/v1/projects/{projectId}/features/{id}` (name + description only)
- On save: refresh feature list

#### 3.3 Feature Detail Panel / Drawer (`src/components/features/FeatureDetail.vue`)
Slide-out `v-navigation-drawer` or dialog opened on row click:
- **Value tab**: 
  - Toggle enabled/disabled for current environment (`PATCH featurestates/{id}`)
  - Edit value field for current environment
  - Tags chip display and management
- **Settings tab**:
  - Edit name and description
  - `defaultEnabled` toggle (via PATCH feature)
  - Danger zone: Delete feature (confirmation requiring re-type of flag name)

#### 3.4 Tags Management (`src/components/features/TagsChipInput.vue`)
- Inline chip input on feature forms
- Autocomplete from `GET /api/v1/projects/{projectId}/tags`
- Create new tag inline (label + color picker)
- `POST /api/v1/projects/{projectId}/tags` on new tag
- Delete unused tags via `DELETE /api/v1/projects/{projectId}/tags/{id}`

#### 3.5 Feature State Value Editor (`src/components/features/FeatureValueEditor.vue`)
- Detects value type (boolean/number/JSON/string) and renders appropriate input
- JSON values get a code editor (simple `v-textarea` with monospace font)
- Saves via `PUT /api/v1/environments/{apiKey}/featurestates/{id}`

#### 3.6 Unit Tests
- FeaturesView: renders list, pagination, toggle state
- FeatureDialog: validation, create call, edit call
- TagsChipInput: loads existing tags, creates new tag
- FeatureDetail: tab switching, delete confirmation

---

## Chunk 4: Segments

### Goals
Full CRUD for project-level segments with a visual rule builder, and segment-level feature state overrides per environment.

### Tasks

#### 4.1 Segments List View (`SegmentsView.vue`)
- Table: Name, Rule Count, Created At, Actions (Edit, Delete)
- "Create Segment" button → opens Segment Editor
- Delete with confirmation dialog

#### 4.2 Segment Editor Dialog (`src/components/segments/SegmentEditor.vue`)
Full-featured rule builder:
- **Name** field
- **Rules section**: List of rule groups (AND/OR type selector)
  - Each rule group contains **Conditions**:
    - Property (trait key, text input)
    - Operator (select from: Equal, NotEqual, Contains, NotContains, Regex, GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual, IsTrue, IsFalse, In, NotIn, IsSet, IsNotSet, PercentageSplit)
    - Value (text input; hidden for IsTrue/IsFalse/IsSet/IsNotSet operators; percentage slider for PercentageSplit)
  - Add/remove conditions within a group
  - Add/remove rule groups
  - Nested child rules supported (recursive component)
- On save: `POST` or `PUT /api/v1/projects/{projectId}/segments`
- Constraint display: shows "X / 100 conditions used"

#### 4.3 Segment Overrides on Features
Within the Feature Detail drawer (Chunk 3):
- **Overrides tab**: list of segments that have overrides for this feature in current environment
  - Each override shows: Segment Name, Enabled toggle, Value
  - "Add Segment Override" button → select segment from dropdown → configure enabled/value
  - Saves via Feature State API (`featureSegmentId` populated)
  - Delete override button

#### 4.4 Unit Tests
- SegmentsView: list, delete
- SegmentEditor: rule builder add/remove conditions, add/remove groups, validation
- Segment overrides: add, remove, toggle

---

## Chunk 5: Identities

### Goals
Admin view of identities in the current environment, with the ability to view traits and override feature states per identity.

### Tasks

#### 5.1 Identities List View (`IdentitiesView.vue`)
- Server-side paginated table: Identifier, Trait Count, Created At, Actions
- Search by identifier
- Click row → Identity Detail

#### 5.2 Identity Detail View (`src/components/identities/IdentityDetail.vue`)
Slide-out panel or separate route `/identities/{id}`:
- **Traits section**: 
  - Table of key/value traits
  - (Read-only in admin view; traits are set via SDK)
- **Feature Overrides section**:
  - Table of all features with current state for this identity
  - Columns: Feature Name, Environment Default, Identity Override (toggle + value), Override Active
  - "Add Override" — select feature → set enabled/value → `PUT /api/v1/environments/{apiKey}/identities/{id}/featurestates/{featureId}`
  - "Remove Override" → `DELETE /api/v1/environments/{apiKey}/identities/{id}/featurestates/{featureId}`
- **Danger Zone**: Delete identity (`DELETE /api/v1/environments/{apiKey}/identities/{id}`)

#### 5.3 Unit Tests
- IdentitiesView: pagination, search
- IdentityDetail: traits display, override toggle, delete identity

---

## Chunk 6: Audit Logs & Webhooks

### Goals
Read-only audit log viewer with filtering and webhook management at organization and environment level.

### Tasks

#### 6.1 Audit Logs View (`AuditLogsView.vue`)
Accessible from both org-level sidebar and within project/environment context:
- Server-side paginated table:
  - Columns: Timestamp, Actor, Action, Resource Type, Resource ID, Project, Environment
  - The `changes` JSON field expandable inline (show diff)
- Filters (Vuetify filter chips / inputs):
  - Date range picker (start/end)
  - Resource Type (multi-select: Feature, Environment, Segment, Identity, Organization, Project, ApiKey)
  - Action (multi-select: Created, Updated, Deleted)
- Scoped by current context: uses org/project/environment audit-logs endpoint appropriately

#### 6.2 Webhooks Management (`src/components/settings/WebhooksPanel.vue`)
Used in both Settings view (org-level) and Environment settings:
- Table: URL (truncated), Enabled toggle, Created At, Actions
- "Add Webhook" button → Webhook Dialog
- Enabled toggle → `PUT` to update `enabled` field
- Delete with confirmation

#### 6.3 Webhook Dialog (`src/components/settings/WebhookDialog.vue`)
- Fields: URL (required), Secret (optional, masked input), Enabled (toggle)
- On create: `POST /api/v1/organisations/{id}/webhooks` or `POST /api/v1/environments/{apiKey}/webhooks`
- On edit: `PUT`

#### 6.4 Webhook Delivery History (`src/components/settings/WebhookDeliveryHistory.vue`)
- Accessible via "View Deliveries" action on each webhook row
- Table: Timestamp, Status (chip: Success/Failed/Pending), Attempt #, HTTP Response Code
- `GET /api/v1/environments/{apiKey}/webhooks/{id}/deliveries`

#### 6.5 Unit Tests
- AuditLogsView: renders data, filter by resource type, filter by date range
- WebhooksPanel: list, toggle enabled, delete
- WebhookDialog: validation, create, edit
- WebhookDeliveryHistory: renders statuses

---

## Chunk 7: Settings, Permissions & API Keys

### Goals
Organization settings, project-level user permissions, and API key management.

### Tasks

#### 7.1 Settings View (`SettingsView.vue`)
Tabbed layout:

**Tab: Organization**
- Edit organization name → `PUT /api/v1/organisations/{id}`
- Organization webhook management (reuse `WebhooksPanel` component from Chunk 6)
- Audit log link (scoped to org)

**Tab: Project**
- Edit project name and `hideDisabledFlags` toggle → `PUT /api/v1/projects/{id}`
- User Permissions table:
  - Columns: User ID, Is Admin, Permissions (chips)
  - "Add User" button → `POST /api/v1/projects/{id}/user-permissions`
  - Edit permissions inline → `PUT /api/v1/projects/{id}/user-permissions/{userId}`
  - Remove user → `DELETE /api/v1/projects/{id}/user-permissions/{userId}`
  - Permission checkboxes: ViewProject, CreateFeature, EditFeature, DeleteFeature, CreateEnvironment, EditEnvironment, DeleteEnvironment, CreateSegment, EditSegment, DeleteSegment, ManageWebhooks, ViewAuditLog

**Tab: Environments**
- List of environments for current project
- Create environment: name input → `POST /api/v1/environments`
- Clone environment button → dialog asking for new name → `POST /api/v1/environments/{apiKey}/clone`
- Rename environment → `PUT /api/v1/environments/{apiKey}`
- Delete environment (with confirmation) → `DELETE`
- Environment webhook management (reuse `WebhooksPanel`)

**Tab: API Keys**
- Table: Name, Prefix (e.g. `org-key-ab`), Active, Expires At, Created At, Actions (Delete)
- "Create API Key" button → dialog:
  - Name field (required)
  - Expiry date picker (optional)
  - `POST /api/v1/organisations/{id}/api-keys`
  - On success: show `rawKey` once in a copy-to-clipboard dialog with warning "This will not be shown again"
- Delete key → `DELETE`

#### 7.2 Profile View (`ProfileView.vue`)
- Display name and email (read-only for now; no user update endpoint exists in current API)
- Logout button → calls auth store `logout()` → redirect to `/login`
- Display current organization memberships

#### 7.3 Organization Members Panel
In Organization tab:
- List members: `GET /api/v1/organisations/{id}/users` → table of userId + role
- Invite user: `POST /api/v1/organisations/{id}/users/invite` (userId + role)
- Remove member: `DELETE /api/v1/organisations/{id}/users/{userId}`

#### 7.4 Unit Tests
- API key creation: shows raw key once, copy to clipboard
- Permission editor: checkboxes update correctly, admin flag overrides individual permissions
- Environment settings: clone, rename, delete
- Profile: logout flow

---

## Shared Components & Utilities

### `src/components/common/`
- `ConfirmDialog.vue` — reusable confirm dialog (message, confirm label, danger variant)
- `PaginatedTable.vue` — wraps `v-data-table-server` with standard pagination controls
- `CopyTextField.vue` — input with copy-to-clipboard button (used for API keys, env keys)
- `StatusChip.vue` — colored chip for Success/Failed/Pending/Enabled/Disabled
- `DateRangePicker.vue` — reusable date range filter input
- `EmptyState.vue` — centered icon + message + action button for empty lists

### `src/composables/`
- `usePagination.ts` — manages page/pageSize state and server-side data fetching
- `useConfirm.ts` — returns a promise-based confirm dialog trigger
- `useNotifications.ts` — wraps Vuetify `v-snackbar` for success/error toasts

### `src/types/api.ts`
Complete TypeScript interfaces for all API response and request models.

---

## File Structure Target

```
src/admin/src/
├── api/
│   ├── client.ts              # Axios instance + interceptors
│   ├── auth.ts
│   ├── organizations.ts
│   ├── projects.ts
│   ├── environments.ts
│   ├── features.ts
│   ├── featureStates.ts
│   ├── segments.ts
│   ├── tags.ts
│   ├── identities.ts
│   ├── auditLogs.ts
│   ├── webhooks.ts
│   └── apiKeys.ts
├── stores/
│   ├── auth.ts
│   └── context.ts
├── types/
│   └── api.ts
├── composables/
│   ├── usePagination.ts
│   ├── useConfirm.ts
│   └── useNotifications.ts
├── components/
│   ├── common/
│   │   ├── ConfirmDialog.vue
│   │   ├── PaginatedTable.vue
│   │   ├── CopyTextField.vue
│   │   ├── StatusChip.vue
│   │   ├── DateRangePicker.vue
│   │   └── EmptyState.vue
│   ├── nav/
│   │   ├── OrgSelector.vue
│   │   ├── ProjectSelector.vue
│   │   └── EnvironmentTabBar.vue
│   ├── features/
│   │   ├── FeatureDialog.vue
│   │   ├── FeatureDetail.vue
│   │   ├── FeatureValueEditor.vue
│   │   └── TagsChipInput.vue
│   ├── segments/
│   │   ├── SegmentEditor.vue
│   │   ├── RuleGroupEditor.vue
│   │   └── ConditionEditor.vue
│   ├── identities/
│   │   └── IdentityDetail.vue
│   └── settings/
│       ├── WebhooksPanel.vue
│       ├── WebhookDialog.vue
│       ├── WebhookDeliveryHistory.vue
│       └── PermissionsEditor.vue
├── views/
│   ├── LoginView.vue
│   ├── RegisterView.vue
│   ├── DashboardView.vue
│   ├── FeaturesView.vue
│   ├── SegmentsView.vue
│   ├── IdentitiesView.vue
│   ├── AuditLogsView.vue
│   ├── SettingsView.vue
│   └── ProfileView.vue
├── plugins/
│   └── vuetify.ts
├── router/
│   └── index.ts
├── App.vue
└── main.ts
```

---

## Build Order Summary

| Chunk | Description | Depends On |
|-------|-------------|------------|
| 1 | Foundation: API client, Auth, Pinia stores, Login/Register | — |
| 2 | Navigation, context selectors, route guards, Dashboard | Chunk 1 |
| 3 | Feature Flags (list, CRUD, env state toggles, tags) | Chunk 2 |
| 4 | Segments (list, rule builder, overrides) | Chunk 3 |
| 5 | Identities (list, detail, per-identity overrides) | Chunk 3 |
| 6 | Audit Logs & Webhooks | Chunk 2 |
| 7 | Settings, Permissions, API Keys, Profile | Chunk 2 |

Each chunk can be built and committed independently after Chunk 2 is complete.