# Implementation Plan - AuraK External API Service (v2.0)

Provide an API service for external systems to access the KnowledgeBase functionalities, including chat, search, and document management.

## User Review Required

> [!IMPORTANT]
> **Multi-Tenancy & Resource Sharing**:
> - **Tenant Entity**: We will introduce a `Tenant` (Organization) entity.
> - **Resource Scoping**: `User`, `KnowledgeBase`, `KnowledgeGroup`, `SearchHistory`, `Note`, and `ImportTask` will be scoped by `tenantId`.
> - **Configuration Hierarchy**:
>     - **ModelConfig**: Inherited hierarchy: `System Models (Global)` -> `Tenant Models (Shared in Org)` -> `User Models (Private)`.
>     - **TenantSettings**: New entity to define organization-wide defaults (Language, Default Models, Search thresholds). `UserSetting` can still override these for personalization.
> - **Data Migration**: Existing data will be migrated to a "Default Tenant" during the first run.
> - **Elasticsearch Isolation**: The `tenantId` field will be added to the ES mapping and enforced in all search/delete queries.
> - **Storage Partitioning**: Uploaded files will be stored in `uploads/{tenantId}/{fileId}` to isolate files at the filesystem level.
> - **API Key**: Tied to `User`, and all operations will be automatically scoped to the user's and tenant's data range.

> [!IMPORTANT]
> **RBAC & Interface Separation**:
> - **Roles**:
>     - `SUPER_ADMIN`: Manage Tenants and global system settings.
>     - `TENANT_ADMIN`: Manage Users and Knowledge Bases within their Tenant.
>     - `USER`: Access Chat, Search, and Knowledge Base within their Tenant.
> - **API Separation**: Administrative endpoints will be separated into `/api/v1/super-admin/*` and `/api/v1/admin/*`.
> - **UI Separation**: Recommend separating the "Admin Portal" from the "User Workspace" to ensure a cleaner user experience and better security boundaries.

> [!IMPORTANT]
> **Frontend Modernization & Boundary Separation (Google Workspace Style)**:
> - **Design Aesthetic**: Adopt a clean, modern, and professional style inspired by Google Workspace (Gmail, Drive, Gemini), following Material Design 3 specifications.
> - **Frontend Boundary Separation**:
>     - **User Workspace**: Focused purely on end-user tools (Chat, Notebooks, Personal Settings).
>     - **Admin Dashboard**: Dedicated area for management (Knowledge Base files, System/Tenant Settings, Global Models).
>     - **Implementation**: We will introduce `react-router-dom` to provide clear URL boundaries (e.g., `/` for workspace and `/admin` for management) OR use a strict state-based layout split (`WorkspaceLayout` vs `AdminLayout`) with an app switcher.
> - **Core Elements**:
>     - **Sleek Navigation Rail**: A minimal, collapsible sidebar with rounded active states, scoped to the current boundary (Admin vs Workspace).
>     - **Top Global Search**: A prominent, rounded search bar for quick access.
>     - **Airy Layout**: Increased white space and soft shadows to improve readability.
>     - **Gemini-like Chat**: A modern AI chat interface with clean message bubbles and a refined input area.
> - **Mockup**:
> ![Google Workspace Style Mockup](./google_workspace_style_ui_mockup.png)

## Proposed Changes

### [Component] Database Schema
#### [NEW] [tenant.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/tenant/tenant.entity.ts)
- Define `Tenant` entity with `id` and `name`.

#### [MODIFY] [user.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/user/user.entity.ts)
- Add `tenantId` column (ManyToOne relationship with `Tenant`).
- Add `role` column (Enum: `SUPER_ADMIN`, `TENANT_ADMIN`, `USER`).
- Add `apiKey` column for API authentication.

#### [NEW] [tenant-setting.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/tenant/tenant-setting.entity.ts)
- Store organization-wide defaults (similar fields to `UserSetting`).

#### [MODIFY] [model-config.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/model-config/model-config.entity.ts)
- Add `tenantId` column (nullable for global models).
- Update lookup logic to include system-level and tenant-level models.

#### [MODIFY] [knowledge-base.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/knowledge-base/knowledge-base.entity.ts)
- Add `tenantId` column.

#### [MODIFY] [knowledge-group.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/knowledge-group/knowledge-group.entity.ts)
- Add `tenantId` column.

#### [MODIFY] [search-history.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/search-history/search-history.entity.ts)
- Add `tenantId` column.

#### [MODIFY] [note.entity.ts](file:///d:/tmp/KnowledgeBase/server/src/note/note.entity.ts)
- Add `tenantId` column.

### [Component] Infrastructure & Storage
#### [MODIFY] [elasticsearch.service.ts](file:///d:/tmp/KnowledgeBase/server/src/elasticsearch/elasticsearch.service.ts)
- Update `createIndex` mapping to include `tenantId` as a `keyword` field.
- Modify `searchSimilar`, `searchFullText`, and `hybridSearch` to include `term: { tenantId }` filter.

#### [MODIFY] [knowledge-base.service.ts](file:///d:/tmp/KnowledgeBase/server/src/knowledge-base/knowledge-base.service.ts)
- Update file storage logic to use `uploads/{tenantId}/{fileId}` path.

#### [NEW] [migrations]
- Create a migration script to:
    1. Create the `Tenant` table.
    2. Create a "Default" tenant.
    3. Update all existing records to link to the "Default" tenant.

### [Component] User & Auth
#### [NEW] [super-admin.guard.ts](file:///d:/tmp/KnowledgeBase/server/src/auth/super-admin.guard.ts)
- Guard that checks for `SUPER_ADMIN` role.

#### [NEW] [tenant-admin.guard.ts](file:///d:/tmp/KnowledgeBase/server/src/auth/tenant-admin.guard.ts)
- Guard that checks for `TENANT_ADMIN` role or higher within the same tenant.

### [Component] Frontend Separation
#### [MODIFY] [App.tsx](file:///d:/workspace/AuraK/web/App.tsx)
- Introduce a clear layout abstraction: `WorkspaceLayout` and `AdminLayout`.
- Add an "App Switcher" for Admin users to toggle between User Workspace and Admin Dashboard.

#### [NEW] [WorkspaceLayout.tsx](file:///d:/workspace/AuraK/web/components/layouts/WorkspaceLayout.tsx)
- Contains a customized `WorkspaceSidebarRail` showing only user-centric views (`chat`, `notebooks`).

#### [NEW] [AdminLayout.tsx](file:///d:/workspace/AuraK/web/components/layouts/AdminLayout.tsx)
- Contains an `AdminSidebarRail` showing management views (`knowledge`, `settings`).

---

## Verification Plan

### Automated Tests
- `curl -X GET http://localhost:3001/api/v1/knowledge-bases -H "x-api-key: YOUR_KEY"`
- `curl -X POST http://localhost:3001/api/v1/chat -H "x-api-key: YOUR_KEY" -d '{"message": "Hello"}'`

### Manual Verification
1.  **Retrieve API Key**: Login to the system, then call `/api/user/api-key` to get the key.
2.  **Test External Request**: Use the retrieved key to call the new `/api/v1/*` endpoints.
3.  **Check Swagger**: Visit `http://localhost:3001/api/docs`.
4.  **Verify Streaming**: Ensure `POST /api/v1/chat` with `stream: true` returns SSE chunks.