AuraK — Enterprise AI Knowledge Base & Talent Assessment Platform

AuraK is a multi-tenant intelligent platform built with React 19 + NestJS, combining RAG-powered knowledge management, interactive AI assessment, and enterprise-grade RBAC permission system.

---

✨ Features

🔐 Enterprise Multi-Tenant & RBAC

• Tenant Isolation — Strict data isolation between tenants with independent member management
• RBAC Permissions — 3-tier roles (SUPER_ADMIN / TENANT_ADMIN / USER) with 26 granular permissions across 7 categories
• Custom Roles — Create and assign custom roles with specific permission sets
• Permission Matrix UI — Visual permission matrix editor in Settings panel
• Role Auto-Seed — Default roles with permission sets created on startup

📊 Interactive AI Assessment

• AI-Powered Exams — Automated question generation, grading, and follow-up questioning via LangGraph workflow
• Dual Question Sources — Pre-built question banks + AI generation on-the-fly
• Multi-Dimension Scoring — Weighted scoring across customizable dimensions (Prompt, LLM, IDE, Dev Patterns, Work Capability)
• Certificate System — Auto-generated certificates with score breakdown by dimension
• Adaptable Templates — Configure question count, dimensions, time limits, passing scores per template
• Non-Technical Mode — Separate templates for non-technical staff (exclude IDE/Dev Patterns)

Exam Flow: Admin creates accounts → Candidates login → Take assessment → AI grades + issues certificate → View history

📚 Intelligent Knowledge Base

• Dual Processing Modes — Fast mode (Tika text extraction) + High-precision mode (Vision Pipeline for image/PDF)
• Hybrid Search — BM25 keyword + vector embedding with Elasticsearch
• Multi-Format Support — PDF, Word, PPT, Excel, images
• Hierarchical Groups — Folder-style knowledge group management

🤖 Multi-Model AI Engine

• OpenAI-compatible APIs (OpenAI, DeepSeek, Claude, etc.)
• Google Gemini native SDK
• Configurable LLM / Embedding / Rerank / Vision models

🌐 Additional Features

• Streaming SSE responses
• Multi-language (Chinese, English, Japanese)
• Feishu (Lark) bot integration
• Podcast generation from documents
• Notebook/shared notes system
• User quota management

---

🏗️ Tech Stack

Frontend

• Framework: React 19 + TypeScript + Vite 6
• Styling: Tailwind CSS v4 + custom design system
• Icons: Lucide React
• State: React Context
• UI Components: Framer Motion, react-router-dom v7

Backend

• Framework: NestJS 11 + TypeScript
• AI Engine: LangChain + LangGraph (assessment workflow)
• Database: SQLite (better-sqlite3, metadata) + Elasticsearch 9 (vector + full-text)
• Auth: JWT + API Key dual mechanism
• Document Processing: Apache Tika + Vision Pipeline + LibreOffice

Infrastructure

• Docker Compose (Elasticsearch, Tika, LibreOffice)
• Nginx reverse proxy (production)

---

🚀 Quick Start

Prerequisites

• Node.js 18+, Yarn
• Docker & Docker Compose

1. Install & Start

# Clone and install
git clone <repo-url>
cd AuraK
yarn install

# Configuration
cp server/.env.sample server/.env
# Edit server/.env — set JWT_SECRET, API keys

# Start infrastructure (optional — AI features need Elasticsearch)
docker-compose up -d elasticsearch tika libreoffice

# Start development servers
yarn dev
# Frontend: http://localhost:13001
# Backend:  http://localhost:3001

2. Default Login

Username: admin
Password: admin123

3. Quick Start (without Docker)

# Start backend (production mode)
cd server && node dist/main.js &

# Start frontend
cd web && npx vite --port 13001 &

---

📖 User Guide

System Setup & User Management

路径: 系统设置 → 用户管理

1. Create Users — Add users with username, password, display name
2. Assign Roles — Click edit on any user → select USER / TENANT_ADMIN / SUPER_ADMIN
3. Role Preview — Each role shows its permission count
4. Bulk Import/Export — XLSX import and export

Permission Management

路径: 系统设置 → 权限管理

1. Role List — Left panel shows all roles (SUPER_ADMIN, TENANT_ADMIN, USER + custom)
2. Permission Matrix — Click a role → toggle individual permissions
3. Custom Roles — Create role → set permissions → assign to users
4. System Role Protection — Built-in roles cannot be modified

Assessment Setup

路径: 系统设置 → 测评模板

1. Create Template — Set name, question count, passing score, time limits
2. Configure Dimensions — Add/remove dimensions, set weights (e.g., PROMPT:30%, LLM:30%, IDE:20%, DEV_PATTERN:20%)
3. Link Question Bank — Create/attach a question bank with published items
4. AI Generation — If no bank linked, AI generates questions from knowledge base

Running an Exam

路径: 考核评估 → 选择模板 → 开始专业评估

For Organizers (Admin):

1. Go to Settings → User Management → Create student accounts
2. Tell students their credentials

For Candidates:

1. Login with credentials
2. Go to Assessment → Select template → Start
3. Answer multiple-choice and short-answer questions
4. AI may ask follow-up questions (multi-round dialogue)
5. View results after completion

Viewing Results:

• History — Right sidebar on Assessment page shows past attempts
• Details — Click any history entry to see per-question scores
• Certificate — Click "查看证书" to view grade and dimension breakdown
• Export — PDF report and Excel download available

Tenant Management (SUPER_ADMIN only)

路径: 系统设置 → 租户管理

• Create/edit/delete tenants with hierarchical parent-child structure
• Manage tenant members: add users, assign roles (USER / TENANT_ADMIN)
• Separate knowledge bases and settings per tenant
• Data isolation: users in Tenant A cannot see Tenant B's data

---

🔄 Key System Flows

Authentication Flow

Password Login → JWT issued → API Key generated (stored in localStorage)
  → All subsequent requests via x-api-key header
  → x-tenant-id header for tenant context

Question Selection Algorithm

Template dimensions (e.g., PROMPT:30, LLM:30, IDE:20, DEV_PATTERN:20)
  → floor + remainder allocation (guarantees sum = question count)
  → Higher weight dimensions get remainder priority
  → Each dimension's pool shuffled independently
  → Final result shuffled before return

Role → Permission Resolution

User → TenantMember.role (SUPER_ADMIN/TENANT_ADMIN/USER)
  → Maps to Role entity via baseRole
  → RolePermission table gives permission keys
  → Legacy: user.isAdmin = true → ALL permissions

---

🧪 Testing

Playwright test scripts in project root:

Command	Coverage
node test-systematic.mjs	142 tests — auth, CRUD, RBAC, boundary, UI, user stories
node test-e2e-full.mjs	94 tests — full E2E with 3 roles
node test-user-lifecycle.mjs	42 tests — user lifecycle, edge cases
node exam-organizer.mjs	Exam scenario: create students → take exam → view results
node test-permission-flow.mjs	3-role permission boundary verification
node test-multiround.mjs	Multi-round dialogue in assessments

---

🏗️ Project Structure

AuraK/
├── web/                          # React frontend
│   ├── components/
│   │   ├── views/                # Main page components
│   │   │   ├── SettingsView.tsx       # System settings (users, models, tenants)
│   │   │   ├── PermissionSettingsView.tsx  # RBAC permission matrix UI
│   │   │   ├── AssessmentView.tsx    # Assessment flow UI
│   │   │   └── AssessmentTemplateManager.tsx  # Template editor
│   │   ├── PermissionGate.tsx    # Component-level permission gate
│   │   └── LoginPage.tsx         # Login page
│   ├── src/
│   │   ├── contexts/AuthContext.tsx    # Auth state + tenant switching
│   │   ├── hooks/usePermissions.ts    # Permissions hook
│   │   ├── pages/workspace/          # Route pages
│   │   └── services/                 # API clients
│   └── index.tsx                 # Entry + routing
├── server/                       # NestJS backend
│   ├── src/
│   │   ├── auth/
│   │   │   ├── permission/       # RBAC module
│   │   │   │   ├── permission.constants.ts  # 26 permission definitions
│   │   │   │   ├── permission.service.ts     # Resolution + seed
│   │   │   │   ├── permission.guard.ts       # @Permission() guard
│   │   │   │   ├── role.entity.ts            # Role entity
│   │   │   │   ├── role-permission.entity.ts # Role ↔ Permission join
│   │   │   │   ├── role.controller.ts        # Role CRUD API
│   │   │   │   └── permission.controller.ts  # Permission API
│   │   │   ├── roles.guard.ts    # @Roles() guard
│   │   │   └── combined-auth.guard.ts  # Global auth guard
│   │   ├── assessment/
│   │   │   ├── services/question-bank.service.ts  # Question selection algorithm
│   │   │   └── assessment.service.ts     # Session management + grading
│   │   ├── user/                 # User CRUD + controller
│   │   ├── tenant/               # Multi-tenant model
│   │   ├── admin/                # Admin API
│   │   └── super-admin/          # Super admin API
│   └── dist/                     # Compiled output
├── docker-compose.yml
└── test-*.mjs                    # Playwright test scripts

---

🔧 Configuration Reference

Server Environment (server/.env)

Variable	Default	Purpose
PORT	3001	API server port
DATABASE_PATH	./data/metadata.db	SQLite file location
ELASTICSEARCH_HOST	http://127.0.0.1:9200	Elasticsearch endpoint
TIKA_HOST	http://127.0.0.1:9998	Tika text extraction
LIBREOFFICE_URL	http://127.0.0.1:8100	Document conversion
JWT_SECRET	(required)	JWT signing key
UPLOAD_FILE_PATH	./uploads	File storage
MAX_FILE_SIZE	104857600	Upload limit

---

📄 License

See LICENSE file.