AuraK

Enterprise AI Knowledge Base & Talent Assessment Platform.

For AI assistants (Claude Code / OpenCode / Codex / Gemini CLI): See CLAUDE.md for the complete technical reference — all architecture details, permission entities, guard flow, assessment data model, test patterns, and code conventions are documented there.

---

✨ Features

Area	Highlights
Multi-Tenant	Strict data isolation, hierarchical org tree, per-tenant settings
RBAC	3 tiers (SUPER_ADMIN / TENANT_ADMIN / USER), 26 granular permissions, custom roles, visual permission matrix
AI Assessment	Auto question generation (MC + short answer), adaptive follow-up dialogue, weighted multi-dimension scoring, certificate system
Knowledge Base	Dual processing (Fast via Tika / High-Precision via Vision Pipeline), hybrid search (BM25 + vector), multi-format support
AI Engine	Multi-model (OpenAI-compatible + Gemini), configurable LLM/Embedding/Rerank/Vision, SSE streaming
Feishu Bot	WebSocket integration, interactive message cards, mobile assessment

---

🚀 Quick Start

Prerequisites

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

1. Install & Start

git clone <repo-url>
cd AuraK
yarn install
cp server/.env.sample server/.env
# Edit server/.env — set JWT_SECRET

# Start infrastructure (optional for basic features)
docker-compose up -d elasticsearch tika libreoffice

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

2. Quick Start (no Docker)

cd /d/AuraK/server && node dist/main.js &
cd /d/AuraK/web && npx vite --port 13001 &

3. Default Login

Username: admin
Password: admin123

---

📖 User Guide

User Management

Settings → User Management

Action	Steps
Create user	Fill username, password, display name → Create
Edit user	Click Edit icon → Modify info → Select role (USER / TENANT_ADMIN / SUPER_ADMIN) → Save
Change password	Click key icon → Enter new password → Confirm
Delete user	Click trash icon → Confirm
Export/Import	Click Export/Import buttons → XLSX format

Role changes take effect immediately — the user does not need to log out and back in.

Permission Management

Settings → Permission Management

1. Left panel — lists all roles: SUPER_ADMIN, TENANT_ADMIN, USER, and any custom roles
2. Click a role — right panel shows the permission matrix organized by category
3. Toggle permissions — check/uncheck individual items
4. Save — changes take effect immediately
5. Custom roles — click "+" to create, set permissions, then assign to users via User Management

System roles (SUPER_ADMIN, TENANT_ADMIN, USER) are protected — their permissions cannot be modified.

Assessment Templates

Settings → Assessment Templates

Two built-in templates:

Template	Questions	Dimensions	Audience
Technical	20	PROMPT 30%, LLM 30%, IDE 20%, DEV_PATTERN 20%	Developers, Engineers
Non-Technical	10	PROMPT 50%, LLM 30%, WORK_CAPABILITY 20%	Managers, PMs, Designers

Dimensions are fully customizable — add/remove, adjust weights, change question count.

Running an Exam

As an organizer (admin):

1. Go to Settings → User Management → create student accounts
2. Give students their credentials

As a candidate:

1. Login → go to Assessment
2. Select a template → click Start Assessment
3. Multiple choice: click an option → click Confirm
4. Short answer: type your answer in the textarea → click Send
5. The AI may ask follow-up questions — keep answering
6. After all questions, view your score and certificate

Viewing results:

• History — right sidebar on the Assessment page
• Details — click any history entry to see per-question scores
• Certificate — click "View Certificate" for level, total score, dimension scores
• Export — PDF report and Excel download

Tenant Management (SUPER_ADMIN only)

Settings → Tenant Management

• Create/edit/delete tenants with hierarchical parent-child structure
• Manage members: add/remove users, assign roles
• Per-tenant settings (models, knowledge bases, features)
• Data isolation: Tenant A users cannot access Tenant B data

---

🧪 Testing

# Full system test (142 items)
cd /d/AuraK && node test-systematic.mjs

# Exam organizer scenario (create students → take exam → view results)
cd /d/AuraK && node exam-organizer.mjs

All test scripts are in the project root, prefixed with test-*.mjs.

---

📁 Project Structure

AuraK/
├── web/                        # React frontend (:13001)
│   ├── components/views/       # Main page views
│   ├── src/contexts/           # Auth / Language contexts
│   ├── src/hooks/              # usePermissions
│   └── src/services/           # API clients
├── server/                     # NestJS backend (:3001)
│   ├── src/auth/               # Auth + RBAC permission module
│   │   └── permission/         # Role/Permission entities, service, guard
│   ├── src/assessment/         # Assessment subsystem
│   ├── src/user/               # User CRUD
│   ├── src/tenant/             # Multi-tenant
│   └── src/admin/              # Admin API
├── CLAUDE.md                   # AI assistant reference
├── README.md                   # This file
├── README_ZH.md                # 中文说明
├── test-*.mjs                  # Playwright test scripts
└── docker-compose.yml          # Infrastructure

---

🏗️ Tech Stack

Layer	Technology
Frontend	React 19, TypeScript, Vite 6, Tailwind CSS v4, Framer Motion
Backend	NestJS 11, TypeORM, LangChain, LangGraph
Database	better-sqlite3 (metadata) + Elasticsearch 9 (vector/text search)
Auth	JWT + API Key
AI	OpenAI-compatible (DeepSeek, Claude) + Google Gemini
Infra	Docker Compose (ES, Tika, LibreOffice) + Nginx

---

🔧 Configuration

Variable	Default	Purpose
PORT	3001	Backend port
DATABASE_PATH	./data/metadata.db	SQLite path
ELASTICSEARCH_HOST	http://127.0.0.1:9200	Search engine
JWT_SECRET	(required)	JWT signing secret
UPLOAD_FILE_PATH	./uploads	File storage
MAX_FILE_SIZE	104857600	Upload limit (100MB)

---

🔗 Related Documents

Document	Audience	Content
CLAUDE.md	AI assistants + Developers	Full technical reference: architecture, entities, API, permission system, assessment model, testing patterns
README_ZH.md	Chinese-speaking users	Complete Chinese user guide
STARTUP.md	Operators	Startup scripts and environment setup
VERSION.md	All	Version history and changelog