Skip to content

Commit e931a39

Browse files
jona7ojona7o
committed
feat: v1.0.0 release - LibreChat Admin Dashboard
BREAKING: Initial stable release Features: - Dashboard for monitoring LibreChat AI usage metrics - Token usage statistics (input/output tokens by model) - User activity tracking (active users, conversations) - Model usage breakdown by provider - Request heatmap visualization - MCP tool call statistics - File processing metrics - Web search usage stats - Date range filtering with presets - Dark/Light theme support - Export functionality Technical: - Next.js 15 with App Router - MongoDB aggregation pipelines optimized for LibreChat schema - Jotai state management - Material UI v7 components - Full TypeScript support - Biome for linting/formatting - Jest test suite with LibreChat schema compatibility tests Fixes: - Fixed request counting in getModelTimeSeries (count completion only) - Repository tests aligned with actual pipeline implementations Documentation: - Added AGENTS.md with LibreChat schema compatibility guidelines - Added MIT LICENSE - Updated README with deployment instructions
1 parent f4d932b commit e931a39

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+1873
-1222
lines changed

‎.dockerignore‎

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,49 @@
1+
# Build outputs
12
.next
3+
out
4+
build
5+
dist
6+
7+
# Dependencies (installed in container)
28
node_modules
9+
10+
# Git
311
.git
412
.gitignore
13+
14+
# IDE
15+
.vscode
16+
.idea
17+
18+
# OS
519
.DS_Store
20+
21+
# Docs
622
README.md
7-
.vscode
8-
.idea
23+
docs/
24+
25+
# Tests
26+
__tests__
27+
*.test.ts
28+
*.test.tsx
29+
coverage
30+
jest.config.ts
31+
jest.setup.ts
32+
33+
# CI/CD
34+
.github
35+
36+
# Env files
37+
.env
38+
.env.*
39+
!.env.example
40+
41+
# Dev files
42+
*.log
43+
.swc
44+
*.tsbuildinfo
45+
46+
# Docker files
47+
Dockerfile*
48+
docker-compose*
49+
.dockerignore

‎.github/workflows/ci.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
lint-and-test:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@v4
16+
17+
- name: Setup Node.js
18+
uses: actions/setup-node@v4
19+
with:
20+
node-version: '22.x'
21+
cache: 'npm'
22+
23+
- name: Install dependencies
24+
run: npm ci
25+
26+
- name: Check formatting
27+
run: npm run format:check
28+
29+
- name: Lint
30+
run: npm run lint
31+
32+
- name: Type check
33+
run: npm run type-check
34+
35+
- name: Build
36+
run: npm run build
37+
38+
- name: Run tests
39+
run: npm test

‎.github/workflows/release.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: Release Docker Image
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
env:
9+
REGISTRY: ghcr.io
10+
IMAGE_NAME: ${{ github.repository }}
11+
12+
jobs:
13+
build-and-push:
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: read
17+
packages: write
18+
19+
steps:
20+
- name: Checkout repository
21+
uses: actions/checkout@v4
22+
23+
- name: Setup Node.js
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: '22.x'
27+
cache: 'npm'
28+
29+
- name: Install dependencies
30+
run: npm ci
31+
32+
- name: Run tests
33+
run: npm test
34+
35+
- name: Build TypeScript
36+
run: npm run build
37+
38+
- name: Set up Docker Buildx
39+
uses: docker/setup-buildx-action@v3
40+
41+
- name: Log in to Container Registry
42+
uses: docker/login-action@v3
43+
with:
44+
registry: ${{ env.REGISTRY }}
45+
username: ${{ github.actor }}
46+
password: ${{ secrets.GITHUB_TOKEN }}
47+
48+
- name: Extract metadata (tags, labels)
49+
id: meta
50+
uses: docker/metadata-action@v5
51+
with:
52+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
53+
tags: |
54+
type=semver,pattern={{version}}
55+
type=semver,pattern={{major}}.{{minor}}
56+
type=semver,pattern={{major}}
57+
type=sha,prefix=sha-
58+
type=raw,value=latest,enable={{is_default_branch}}
59+
60+
- name: Build and push Docker image
61+
uses: docker/build-push-action@v6
62+
with:
63+
context: .
64+
push: true
65+
tags: ${{ steps.meta.outputs.tags }}
66+
labels: ${{ steps.meta.outputs.labels }}
67+
cache-from: type=gha
68+
cache-to: type=gha,mode=max
69+
platforms: linux/amd64,linux/arm64
70+
build-args: |
71+
BUILDKIT_INLINE_CACHE=1

‎AGENTS.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# AI Agent Instructions for LibreChat Admin Dashboard
2+
3+
This document provides critical guidelines for AI agents (LLMs) working on this codebase.
4+
5+
## ⚠️ Critical: LibreChat Schema Compatibility
6+
7+
This dashboard connects directly to LibreChat's MongoDB database. **All metrics, queries, and data structures MUST remain compatible with the official LibreChat schema.**
8+
9+
### Before Making Changes
10+
11+
1. **Consult LibreChat Source Code**: Always reference the official LibreChat repository at `danny-avila/LibreChat` before modifying:
12+
- Database queries or aggregation pipelines
13+
- Type definitions for database entities
14+
- Token counting or billing logic
15+
- User, conversation, or message handling
16+
17+
2. **Key LibreChat Schema Files**:
18+
- `packages/data-schemas/src/schema/transaction.ts` - Transaction/billing schema
19+
- `packages/data-schemas/src/schema/message.ts` - Message schema
20+
- `packages/data-schemas/src/schema/convo.ts` - Conversation schema
21+
- `api/models/spendTokens.js` - Token spending logic
22+
23+
3. **Run Compatibility Tests**: After any change, run `npm test` to verify LibreChat schema compatibility tests pass.
24+
25+
## 📊 Token Counting Logic
26+
27+
LibreChat uses specific token counting conventions that this dashboard must follow:
28+
29+
### Transaction-Based Token Counting (Accurate Billing)
30+
```typescript
31+
// Transactions store rawAmount as NEGATIVE for spending
32+
// Always use $abs when summing tokens
33+
{ $sum: { $abs: "$rawAmount" } }
34+
35+
// Token types:
36+
// - "prompt" = input tokens
37+
// - "completion" = output tokens
38+
// - "credits" = credit-based billing
39+
```
40+
41+
### Message-Based Token Counting (Per-Message)
42+
```typescript
43+
// messages.tokenCount = tokens for individual message only
44+
// Does NOT include full conversation context
45+
// Use transactions for accurate API consumption metrics
46+
```
47+
48+
### Structured Token Fields (Cache-Aware)
49+
```typescript
50+
// Modern LibreChat transactions may include:
51+
interface StructuredTokens {
52+
inputTokens?: number; // Total input tokens
53+
writeTokens?: number; // Cache write tokens
54+
readTokens?: number; // Cache read tokens (discounted)
55+
}
56+
```
57+
58+
## 🔗 MCP Tool Call Detection
59+
60+
MCP (Model Context Protocol) tools are identified by delimiter patterns in tool names:
61+
62+
```typescript
63+
// MCP tool name formats:
64+
// - toolName_mcp_serverName (e.g., "search_mcp_brave")
65+
// - toolName::serverName (e.g., "read_file::filesystem")
66+
67+
const MCP_DELIMITER = "(_mcp_|::)";
68+
69+
// Tool calls are stored in messages.content[] as:
70+
{
71+
type: "tool_call",
72+
tool_call: {
73+
name: "toolName_mcp_serverName",
74+
// ...
75+
}
76+
}
77+
```
78+
79+
## 🏗️ Architecture Guidelines
80+
81+
### Repository Pattern
82+
- All database queries go through `src/lib/db/repositories/`
83+
- Use pipeline builders from `src/lib/db/pipeline-builders.ts` for consistency
84+
- Types must match LibreChat schemas in `src/lib/db/types.ts`
85+
86+
### API Routes
87+
- Located in `src/app/api/`
88+
- Use Zod validation for query parameters
89+
- Always validate date ranges and handle edge cases
90+
91+
### State Management
92+
- Jotai atoms in `src/atoms/`
93+
- Use `useLoadableWithCache` hook for data fetching
94+
95+
## 🧪 Testing Requirements
96+
97+
### Before Any PR/Commit
98+
99+
1. **Format Check**: `npm run format:check`
100+
2. **Type Check**: `npm run type-check`
101+
3. **Tests**: `npm test`
102+
103+
### Test Categories
104+
105+
| Test File | Purpose |
106+
|-----------|---------|
107+
| `librechat-schema-compatibility.test.ts` | Verify types match LibreChat schemas |
108+
| `pipeline-builders.test.ts` | MongoDB aggregation pipeline correctness |
109+
| `date-validation.test.ts` | Date handling and LibreChat compatibility |
110+
| `*-repository.test.ts` | Repository function behavior |
111+
112+
### Writing New Tests
113+
114+
When adding features that interact with LibreChat data:
115+
116+
1. Add schema compatibility tests verifying field names and types
117+
2. Test with realistic LibreChat data patterns
118+
3. Consider edge cases: null models, agent endpoints, empty conversations
119+
120+
## 🚫 Common Mistakes to Avoid
121+
122+
### ❌ Don't Do This
123+
124+
```typescript
125+
// Wrong: Using messages.tokenCount for billing metrics
126+
{ $sum: "$tokenCount" }
127+
128+
// Wrong: Forgetting $abs on transaction amounts
129+
{ $sum: "$rawAmount" } // rawAmount is negative!
130+
131+
// Wrong: Hardcoding endpoint names
132+
endpoint: "openai" // Should be "openAI" (camelCase)
133+
134+
// Wrong: Ignoring null models
135+
$match: { model: "gpt-4" } // Missing null check
136+
```
137+
138+
### ✅ Do This Instead
139+
140+
```typescript
141+
// Correct: Use transactions with $abs for billing
142+
{ $sum: { $abs: "$rawAmount" } }
143+
144+
// Correct: Filter null models
145+
$match: { model: { $ne: null } }
146+
147+
// Correct: Use LibreChat endpoint values
148+
// "openAI", "google", "anthropic", "agents", "assistants", "azureOpenAI", "bedrock"
149+
```
150+
151+
## 📋 Pre-Release Checklist
152+
153+
Before releasing a new version:
154+
155+
- [ ] All tests pass (`npm test`)
156+
- [ ] No format errors (`npm run format:check`)
157+
- [ ] No type errors (`npm run type-check`)
158+
- [ ] Docker build succeeds (`docker build .`)
159+
- [ ] Tested against real LibreChat MongoDB instance
160+
- [ ] Schema compatibility tests cover new features
161+
- [ ] No breaking changes to existing API routes
162+
163+
## 🔄 When LibreChat Updates
164+
165+
If LibreChat releases schema changes:
166+
167+
1. Review LibreChat changelog and migration notes
168+
2. Update `src/lib/db/types.ts` to match new schemas
169+
3. Update affected repository queries
170+
4. Add/update schema compatibility tests
171+
5. Bump dashboard version appropriately
172+
173+
## 📚 Resources
174+
175+
- [LibreChat GitHub](https://github.com/danny-avila/LibreChat)
176+
- [LibreChat Docs](https://docs.librechat.ai)
177+
- [MongoDB Aggregation](https://www.mongodb.com/docs/manual/aggregation/)
178+
- [Next.js App Router](https://nextjs.org/docs/app)

0 commit comments

Comments
 (0)