​

Database Architecture

​

Overview

Zeus uses a layered database architecture that separates database operations from business logic, achieving clear separation of concerns.

​

Architecture Overview

​

Layer Responsibilities

​

1. Schema Layer

Defines table structures and relationships using Drizzle ORM’s declarative syntax for database tables, field types, constraints, and foreign key relationships.

​

2. Model Layer

Encapsulates single-table CRUD operations, providing standard methods like findById, findByUserId, create, update, and delete. Each Model corresponds to one database table.

​

3. Service Layer

Handles business logic, including cross-model transactions and coordinated operations. For example, creating a session while simultaneously adding the first message, or cascade-deleting all messages when a session is deleted.

​

4. API Route Layer

Handles HTTP requests, responsible for permission checks, parameter validation, calling the Service layer, and returning responses. API Routes do not directly operate on the database.

---

​

Drizzle ORM

​

Overview

Zeus uses Drizzle ORM for type-safe database operations with PostgreSQL.

​

Database Tables

The system contains the following database tables (defined in db/schema/): Authentication & User:

• user - User information (id, name, email, emailVerified, image, etc.)
• session - User sessions (linked to user, includes token and expiration time)
• account - OAuth accounts (linked to user, stores third-party login information)
• user_settings - User preference settings
• invitation_code - Invitation codes for registration

Chat & Sessions:

• chat_session - Chat sessions (linked to user and project)
• message - Message records (linked to chat_session, includes role, content, and tool call information)
• checkpoint - Agent state checkpoints for session recovery

Projects:

• project - Project management (linked to user)
• settings - Project-level settings

Knowledge Base:

• knowledge_base - Knowledge base metadata (linked to user)
• embedding - Embedding configuration for vector search

Tools & Skills:

• tools - MCP server and tool configuration (linked to user, includes tools and prompts)
• tool_allowlist - Auto-run tool allowlist per user
• skills - Skill configuration and metadata

AI & Agent:

• llm - LLM model configuration per user
• memory - Long-term memory entries (linked to user)
• sandbox - Sandbox environment configuration
• plan - Agent plan records

Automation & Credits:

• scheduled_task - Scheduled task definitions
• credits - User credit balance and transaction records

Showcase:

• showcase - Published showcase entries

​

Type Safety

Drizzle automatically generates TypeScript types from schema definitions via InferSelectModel and InferInsertModel, ensuring type safety for query and insert operations.

​

Best Practices

​

1. Use Connection Pooling

Configure a database connection pool (recommended max: 20) with reasonable timeout parameters to optimize performance.

​

2. Add Indexes

Add indexes on frequently queried fields, such as foreign key fields like userId and projectId.

​

3. Use Transactions

For multi-step operations requiring atomicity, use db.transaction() to ensure data consistency.

​

4. Batch Operations

Prefer batch inserts and IN queries over individual operations in loops.