Content
# AI-Powered Internal Document Assistant
A full-stack TypeScript workspace for an internal, evidence-grounded document assistant. The application combines a modular React client, a NestJS API, PostgreSQL persistence, MCP tools, and retrieval-augmented generation over imported documents.
## What is implemented
- Email/password signup and login with JWT-protected chat endpoints.
- Persistent conversations with recent-message history.
- Plain-text document import, legal/paragraph-aware chunking, and OpenAI embeddings.
- Document list, search, detail, chunk inspection, delete, and embedding reindex APIs.
- Selected-document or all-accessible-document chat scope.
- Hybrid keyword/vector retrieval with optional user and document isolation.
- Grounded AI answers with structured citations.
- Conversation memory and token-budgeted prompt assembly.
- MCP JSON-RPC endpoint with chat tools.
- React workspaces for chat, document import, document management, and a disabled retrieval-debug placeholder.
## Technology
### Client
- React 19 and TypeScript
- Ant Design 6
- Clean Architecture with feature-owned modules
- MVVM-style ViewModels using RxJS `BehaviorSubject`
- `tsyringe` dependency injection
- Redux Toolkit for shared authentication/session state
- Axios API client
### Server
- NestJS 11 and TypeScript
- Clean Architecture with use cases, domain contracts, symbol-token DI, and infrastructure adapters
- Prisma 6 with PostgreSQL
- JWT and bcrypt authentication
- OpenAI Responses and Embeddings APIs
- Jest unit and integration tests
## Repository structure
```text
.
├── client/ React application
│ └── src/features/ Feature-owned client modules
├── server/ NestJS application
│ ├── prisma/ Schema and migrations
│ ├── src/auth/ Authentication and JWT guard
│ ├── src/chat/ Stored messages and AI handoff
│ ├── src/mcp/ MCP endpoint and tool registry
│ └── src/aiEmbedding/ Ingestion, RAG, retrieval, memory, prompts, providers
├── .codex/skills/
│ ├── client-skills/ Client architecture and feature skills
│ └── server-skills/ Server architecture and feature skills
└── scripts/ Workspace utilities
```
## Prerequisites
- Node.js and npm
- PostgreSQL
- An OpenAI API key for document import/reindex and full AI generation
Without `OPENAI_API_KEY`, chat generation can use the local grounded fallback when evidence already exists, but document embedding operations cannot run.
## Setup
### 1. Install dependencies
Run from the repository root:
```bash
npm install
```
The root package uses npm workspaces for `client` and `server`.
### 2. Configure the client
Copy `client/.env.example` to `client/.env` and set:
```env
REACT_APP_BASE_URL=http://localhost:3000
```
The client development server runs on port `3001`.
### 3. Configure the server
Create `server/.env`:
```env
DATABASE_URL=postgresql://USER:PASSWORD@localhost:5432/DATABASE
JWT_SECRET=replace-with-a-long-random-secret
PORT=3000
OPENAI_API_KEY=your-api-key
OPENAI_MODEL=gpt-4.1-mini
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
```
`OPENAI_MODEL` and `OPENAI_EMBEDDING_MODEL` are optional; the shown values are the current defaults.
### 4. Prepare Prisma
```bash
cd server
npx prisma generate
npx prisma migrate dev
```
For an already-migrated production or CI database:
```bash
cd server
npx prisma migrate deploy
```
### 5. Run the applications
In separate terminals from the repository root:
```bash
npm --workspace server run start:dev
npm --workspace client run start
```
- Client: `http://localhost:3001`
- Server: `http://localhost:3000`
- API prefix: `http://localhost:3000/api/v1`
## Client routes
| Route | Purpose |
| --- | --- |
| `/login` | Login and signup |
| `/documents` | Document workspace |
| `/documents/import` | Plain-text document import |
| `/chat` | Selected-document RAG chat |
| `/retrieval-debug` | Admin/debug placeholder; server search API is not implemented yet |
## API overview
Successful application responses use:
```json
{
"code": 0,
"message": "Success",
"data": {}
}
```
NestJS exceptions provide HTTP error responses for invalid, unauthorized, or missing resources.
### Authentication
| Method | Endpoint | Notes |
| --- | --- | --- |
| `POST` | `/api/v1/auth/login` | Returns user and access token |
| `POST` | `/api/v1/auth/sign-up` | Creates a user and returns a token |
### Chat and RAG
| Method | Endpoint | Notes |
| --- | --- | --- |
| `GET` | `/api/v1/chat/messages` | JWT required; accepts `conversationId` and `limit` |
| `POST` | `/api/v1/chat/messages` | JWT required; stores user/assistant messages and returns AI metadata |
| `POST` | `/api/v1/ai/chat/complete` | Direct RAG completion without chat-message persistence |
Chat requests support `scopeMode: "all_accessible"` or `"selected_documents"` and an optional `documentIds` array. AI responses include structured citations when relevant chunks are retrieved.
### Documents
| Method | Endpoint | Notes |
| --- | --- | --- |
| `POST` | `/api/v1/ai/documents/import` | Imports plain text and creates embeddings |
| `GET` | `/api/v1/ai/documents` | Supports `userId`, `search`, and `limit` |
| `GET` | `/api/v1/ai/documents/:documentId` | Optional `userId` scope |
| `GET` | `/api/v1/ai/documents/:documentId/chunks` | Ordered chunk inspection |
| `DELETE` | `/api/v1/ai/documents/:documentId` | Deletes the document and cascades its chunks |
| `POST` | `/api/v1/ai/documents/:documentId/reindex` | Rebuilds embeddings for existing chunks |
The current document endpoints accept an optional `userId` query/body scope but are not JWT-guarded. Treat this as an MVP boundary, not complete authorization.
### MCP
`POST /api/v1/mcp` supports:
- `initialize`
- `tools/list`
- `tools/call`
Registered tools:
- `chat.get_messages`
- `chat.send_message`
Example:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "chat.send_message",
"arguments": {
"conversationId": "global",
"content": "Summarize the selected evidence."
}
}
}
```
The MCP endpoint is currently unguarded.
## Verification
```bash
# Server
npm --workspace server run build
npm --workspace server test -- --runInBand
# Client
npm --workspace client run build
# Workspace lint
npm run lint
```
The client build is the primary frontend verification because client test coverage is currently limited.
## Architecture skills
Project-specific Codex guidance lives under `.codex/skills`:
- `client-skills/`: client architecture, design system, document workflows, RAG chat, and retrieval debug.
- `server-skills/`: server architecture, auth, chat, MCP, document lifecycle, RAG, retrieval, memory, prompt runtime, and AI providers.
Every skill requires implementation work to be recorded in its own `audit-log.md`.
## Current limitations
- Document import supports plain text, not multipart PDF/DOCX/TXT upload.
- Retrieval vectors are stored as JSON and ranked in application code; pgvector/indexed vector search is not implemented.
- The retrieval-debug client is a placeholder because `POST /api/v1/ai/retrieval/search` is not implemented.
- Document and MCP endpoints still need complete authentication/authorization enforcement.
- Conversation ownership, teams, organizations, ACLs, and audit persistence are not implemented.
