Backend Server (Express + tRPC)
Relevant source files
The following files were used as context for generating this wiki page:
The Backend Server serves as the core orchestration layer for the bl1nk platform, built using Node.js, Express, and tRPC. It is designed to handle complex AI integration logic, skill management, and credential orchestration while maintaining a stateless architecture. The system leverages tRPC over traditional REST to provide end-to-end type safety between the server and the various client-side applications in the monorepo.
Sources: Comprehensive.md:20-25, specs/main/plan.md:10-15
Architecture and Core Technologies
The backend architecture follows a modular service-oriented pattern within a pnpm monorepo. It integrates several key technologies to handle data persistence, AI communication, and API routing:
- API Layer: tRPC over Express for type-safe communication.
- Database ORM: Prisma ORM interacting with SQLite (Phase 1).
- AI Integration: Communication with AWS Bedrock and OpenRouter via specialized service layers.
- Package Management: Part of a monorepo structure utilizing
packages/sharedfor cross-boundary types.
Sources: Comprehensive.md:20-25, specs/main/plan.md:35-40
System Data Flow
The following diagram illustrates the high-level data flow from the client through the tRPC routers to the persistent storage and AI providers.
The diagram shows the request lifecycle where the client initiates a tRPC call that is processed by the Express-hosted tRPC router, which then delegates business logic to specialized services.
Sources: Comprehensive.md:22-35, specs/main/plan.md:120-130
API Structure and Routers
The API is organized into logical routers that handle specific domains of the application. The primary routers identified in the system are the Skill Router and the Credential Router.
Primary Routers
| Router | Description | Key Responsibilities |
|---|---|---|
skill.router.ts | Skill Management | CRUD operations, versioning, and restoration of skills. |
credential.router.ts | Provider Management | Managing provider credentials, encryption, and connectivity testing. |
Sources: Comprehensive.md:38-42
Router Interaction Sequence
This sequence diagram depicts a typical interaction for managing skill versions through the backend API.
The sequence demonstrates how tRPC ensures that the data returned from the SQLite database through the service layer remains type-consistent all the way to the UI.
Sources: Comprehensive.md:30-45, specs/main/plan.md:125-135
Data Models and Schema
The backend utilizes Prisma to manage a structured data model centered around Skills and their associated metadata.
Entity Relationships
| Entity | Description | Relationship |
|---|---|---|
| Skill | The primary container for an AI capability. | One-to-Many with SkillVersion |
| SkillVersion | Individual iterations of a skill's logic/prompt. | Belongs to Skill |
| ApiCredential | Encrypted storage for provider-specific keys. | Associated with Skill |
| TestMessage | Ephemeral messages used during skill testing. | Associated with Skill |
| AppSettings | Global key-value configuration. | Independent |
Sources: Comprehensive.md:28-35
The ER diagram represents the core data entities and their cardinality as defined in the server's service logic and Prisma schema.
Sources: Comprehensive.md:28-35
AI Service Integration
A critical component of the backend is the claude-service.ts, which manages the logic for interacting with various AI providers. This service abstracts the complexities of different AI APIs (AWS Bedrock, OpenRouter) into a unified interface for the tRPC routers.
- Prompt Orchestration: Constructing system prompts and managing thinking processes.
- Credential Handling: Decrypting
ApiCredentialrecords to authenticate with external providers. - Thinking Process: Implementing structured thinking tags (
<think>) as part of the AI response lifecycle.
Sources: apps/client/src/prompts/system_prompt.ts:7-25, Comprehensive.md:310-315
Development and Tooling Patterns
The backend implementation follows strict TypeScript patterns, especially when building MCP (Model Context Protocol) servers or internal tools.
- Input Validation: Mandatory use of Zod schemas for all router inputs to ensure runtime type safety.
- Error Handling: Use of standardized error handling patterns to provide clear, actionable messages for the AI agents and end-users.
- Strict Typing: Prohibition of the
anytype in favor of proper interfaces orunknown.
Sources: skill/mcp-builder/reference/node_mcp_server.md:85-110, skill/mcp-builder/reference/node_mcp_server.md:265-280
Implementation Guidelines for Backend Extensions
| Guideline | Requirement |
|---|---|
| Validation | Use zod with .strict() for all inputs. |
| Async Patterns | Use async/await exclusively for I/O; avoid promise chains. |
| Documentation | Descriptions must be explicitly provided in code for AI discoverability. |
| Composability | Extract common logic (pagination, filtering) into shared utility functions. |
Sources: skill/mcp-builder/reference/node_mcp_server.md:330-350
Summary
The Backend Server (Express + tRPC) provides a robust, type-safe foundation for the bl1nk platform. By combining the speed of Express with the rigid type safety of tRPC and Prisma, it enables complex AI-driven workflows while ensuring data integrity. Its modular design allows for seamless integration of multiple AI providers and facilitates easy maintenance across the monorepo structure.