# AuraK

Enterprise AI Knowledge Base & Talent Assessment Platform.

> **For AI assistants (Claude Code / OpenCode / Codex / Gemini CLI):** See [CLAUDE.md](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

```bash
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)

```bash
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

```bash
# 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](CLAUDE.md) | AI assistants + Developers | Full technical reference: architecture, entities, API, permission system, assessment model, testing patterns |
| [README_ZH.md](README_ZH.md) | Chinese-speaking users | Complete Chinese user guide |
| [STARTUP.md](STARTUP.md) | Operators | Startup scripts and environment setup |
| [VERSION.md](VERSION.md) | All | Version history and changelog |