Backend Development Guide
Viben project backend development best practices
Overview
This directory contains backend development guidelines. The backend is built with TypeScript in packages/core, serving as the foundation for all frontend applications.
Important: packages/core is the sole boundary for all apps to access underlying capabilities.
Architecture
Important: Viben uses a dual-language architecture:
| Component | Language | Purpose |
|---|---|---|
packages/core | TypeScript | Gateway API, CLI, Agent system, MCP client |
backend/browse-mcp | Python | Academic search MCP server (arXiv, PubMed, etc.) |
The guidelines in this directory primarily focus on packages/core (TypeScript).
For Python MCP server development, see Plugin Architecture, which documents the stevedore-based plugin system in backend/browse-mcp.
Guide Index
Core Guides
| Guide | Description | Status |
|---|---|---|
| Directory Structure | Module organization and file layout | Done |
| Plugin Architecture | Python MCP pluggable Provider system | Done |
| Database Guidelines | ORM patterns, queries, migrations | Done |
| Error Handling | Error types, handling strategies | Done |
| Quality Guidelines | Code standards, forbidden patterns | Done |
| Logging Guidelines | Structured logging, log levels | Done |
Gateway API
| Guide | Description | Status |
|---|---|---|
| Gateway Index | Gateway module index | Done |
| Health Check | Health check endpoint | Done |
| Agent API | Agent management API | Done |
| Model API | Model configuration API | Done |
| Session API | Session management API | Done |
| Group Chat API | Group chat API | Done |
| Executor API | Executor execution API | Done |
| Cron API | Scheduled task API | Done |
| Channel API | Channel management API | Done |
| Provider API | Provider configuration API | Done |
| Task API | Task management API | Done |
| Chat List API | Chat list aggregation API | Done |
| Event Stream API | SSE event stream | Done |
| WebSocket | WebSocket real-time communication | Done |
Web API
| Guide | Description | Status |
|---|---|---|
| MCP API | MCP package API | Done |
| Skill API | Skill package API | Done |
| User API | User management API | Done |
| Social API | Social features API | Done |
| Collections API | Collections API | Done |
| Package Management | Common package operations | Done |
Modules
| Guide | Description | Status |
|---|---|---|
| Auth Module | Authentication system | Done |
| Database Module | Database configuration | Done |
| Storage Module | File storage | Done |
| Project Setup | Project initialization | Done |
Deployment
| Guide | Description | Status |
|---|---|---|
| Vercel Deployment | Vercel deployment guide | Done |
| GitHub OAuth | GitHub OAuth integration | Done |
Tech Stack
- Runtime: Node.js + TypeScript
- HTTP Framework: Hono
- AI SDK: Vercel AI SDK
- Configuration: YAML (file-native paradigm)
- Storage: File-based (
~/.viben/) - Telemetry: OpenTelemetry
API Naming Convention
Important: All Gateway API query parameters use snake_case format:
// Correct
workspace_path, include_global, session_id
// Incorrect
workspacePath, includeGlobal, sessionId
Language: Documentation in English, code comments in English.