aurak/docs/2.0/implementation_plan.md

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:

Proposed Changes

[Component] Database Schema

[NEW] tenant.entity.ts

• Define Tenant entity with id and name.

[MODIFY] 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

• Store organization-wide defaults (similar fields to UserSetting).

[MODIFY] 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

• Add tenantId column.

[MODIFY] knowledge-group.entity.ts

• Add tenantId column.

[MODIFY] search-history.entity.ts

• Add tenantId column.

[MODIFY] note.entity.ts

• Add tenantId column.

[Component] Infrastructure & Storage

[MODIFY] 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

• 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

• Guard that checks for SUPER_ADMIN role.

[NEW] tenant-admin.guard.ts

• Guard that checks for TENANT_ADMIN role or higher within the same tenant.

[Component] Frontend Separation

[MODIFY] 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

• Contains a customized WorkspaceSidebarRail showing only user-centric views (chat, notebooks).

[NEW] 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.