KnowledgeBase/web/README.md

AuraK V2 — Frontend (web)

A modern multi-tenant knowledge base and AI assistant platform built with React 19, Vite, and Tailwind CSS.

🏗️ Architecture

The frontend uses React Router for navigation with a clean role-based routing structure:

Route	Access	Description
/login	Public	Password or API Key sign-in
/	All users	Workspace overview
/chat	All users	AI Chat with scope selection
/knowledge	All users	Document (Knowledge Base) management
/notebooks	All users	Notebooks and notes
/settings	All users	Model and app settings
/admin	TENANT_ADMIN+	Team management, share approvals
/admin/tenants	SUPER_ADMIN	Global tenant management
/admin/models	TENANT_ADMIN+	Model configuration

🔐 Authentication

The app supports two login methods:

1. Password login — POST to /api/v1/auth/login, receives an apiKey back
2. Direct API Key — paste the API key directly

All API calls include x-api-key: <key> in the request headers automatically via services/apiClient.ts.

🛠️ Tech Stack

• React 19 + TypeScript
• Vite (dev server + build)
• TailwindCSS v3 (styling)
• React Router v6 (routing)
• framer-motion (animations)
• Lucide React (icons)
• clsx + tailwind-merge (cn() utility)

🚀 Quick Start

1. Install dependencies

cd web
yarn install

2. Configure environment

Copy .env.example to .env and set the backend URL if needed:

VITE_API_BASE_URL=http://localhost:13000

The Vite dev server proxies /api/* to http://localhost:13000 by default (see vite.config.ts).

3. Start the dev server

yarn dev
# → http://localhost:13001

4. Build for production

yarn build
# Output: dist/

📁 Project Structure

web/
├── index.tsx              # App root — BrowserRouter + all routes
├── index.html
├── src/
│   ├── contexts/
│   │   └── AuthContext.tsx        # User auth state (apiKey, user, role)
│   ├── components/
│   │   └── layouts/
│   │       ├── WorkspaceLayout.tsx  # Sidebar + header for main workspace
│   │       └── AdminLayout.tsx      # Admin console layout
│   ├── pages/
│   │   ├── auth/
│   │   │   └── Login.tsx            # Dual-mode login (password + API key)
│   │   ├── workspace/
│   │   │   ├── ChatPage.tsx
│   │   │   ├── KnowledgePage.tsx
│   │   │   ├── NotebooksPage.tsx
│   │   │   └── SettingsPage.tsx
│   │   └── admin/
│   │       ├── SuperAdminPage.tsx   # Tenant management (SUPER_ADMIN)
│   │       └── TenantAdminPage.tsx  # Team management (TENANT_ADMIN)
│   └── utils/
│       └── cn.ts                    # clsx + twMerge helper
├── components/            # Legacy rich view components (still used)
│   └── views/
│       ├── ChatView.tsx
│       ├── KnowledgeBaseView.tsx
│       ├── NotebooksView.tsx
│       └── SettingsView.tsx
└── services/              # API service layer
    ├── apiClient.ts       # Base HTTP client (auto-injects x-api-key)
    ├── chatService.ts     # Streaming chat
    ├── knowledgeBaseService.ts
    └── ...

🔑 Default Credentials (Development)

After running the backend migration, a default super admin is seeded:

• Email: admin@system.local
• Password: admin123

The /api/v1/auth/api-key endpoint returns your API key after login.

⚠️ Troubleshooting

• 401 errors: Your session expired. You will be redirected to /login automatically.
• Upload fails: Ensure the backend is running and the uploads/ directory is writable.
• No AI response: Configure at least one LLM model in /settings or /admin/models.