Contributing Guide

How to set up your development environment and contribute to Epitome.

Development Setup

Follow these steps to get a development environment running locally.

1. Clone and Install

bash

# Clone the repository
git clone https://github.com/gunning4it/epitome.git
cd epitome

# Install API dependencies
cd api && npm install && cd ..

# Install dashboard dependencies
cd dashboard && npm install && cd ..

2. Start the Database

The easiest way to get PostgreSQL with pgvector running locally is with Docker:

bash

# Start only the database container
docker compose up db -d

# Verify it's running
docker compose ps
# Should show: epitome-db-1  running  0.0.0.0:5432->5432/tcp

3. Configure Environment

bash

# Copy the example env file
cp .env.example api/.env

# Edit api/.env with your settings:
#   DATABASE_URL=postgres://postgres:your_password@localhost:5432/epitome
#   JWT_SECRET=any-random-string-for-dev
#   OPENAI_API_KEY=sk-...  (required for entity extraction and embeddings)
#   NODE_ENV=development

4. Initialize the Database

bash

# Run the init script (creates schemas, tables, extensions)
psql -h localhost -U postgres -d epitome -f init.sql

5. Start the Dev Servers

bash

# Terminal 1: Start the API server (with hot reload)
cd api && npm run dev

# Terminal 2: Start the dashboard (Vite dev server)
cd dashboard && npm run dev

The API server will be available at http://localhost:3000 and the dashboard at http://localhost:5173.

Project Structure

text

epitome/
├── api/                          # Hono API server
│   ├── src/
│   │   ├── routes/               # Endpoint handlers (profile, tables, vectors, graph, etc.)
│   │   ├── services/             # Business logic (profileService, vectorService, etc.)
│   │   ├── middleware/           # Auth, rate limiting, consent, error handling
│   │   ├── mcp/                 # MCP server and 9 tool implementations
│   │   ├── validators/          # Zod schemas for request validation
│   │   └── db/                  # Database connection, withUserSchema, Drizzle config
│   ├── tests/                   # Test files (mirrors src/ structure)
│   ├── package.json
│   ├── tsconfig.json
│   ├── tsup.config.ts           # Build config (used for production builds)
│   └── Dockerfile
│
├── dashboard/                    # React SPA
│   ├── src/
│   │   ├── components/          # Reusable UI components
│   │   │   ├── ui/              # shadcn/ui primitives (card, badge, button, etc.)
│   │   │   └── docs/            # Documentation components (DocPage, EndpointBlock, etc.)
│   │   ├── pages/               # Route pages (Profile, Graph, Memories, etc.)
│   │   │   └── docs/            # Documentation pages (you are here!)
│   │   ├── hooks/               # React hooks (useApi, useScrollSpy, etc.)
│   │   └── lib/                 # Utilities, types, API client
│   ├── vite.config.ts
│   ├── package.json
│   └── Dockerfile
│
├── init.sql                      # Database initialization script
├── docker-compose.yml            # Docker Compose for local dev / self-hosting
├── .env.example                  # Template environment variables
├── EPITOME_TECH_SPEC.md          # Technical specification (canonical)
└── EPITOME_DATA_MODEL.md         # Data model specification (canonical)

Running Tests

Epitome uses Vitest for unit and integration tests. The test suite is configured for serial execution to avoid database connection pool contention.

bash

# Run all tests
cd api && npm test

# Run tests in watch mode (re-runs on file change)
cd api && npm run test:watch

# Run a specific test file
cd api && npx vitest run tests/services/vectorService.test.ts

# Run tests matching a pattern
cd api && npx vitest run -t "profile"

# Run with coverage report
cd api && npx vitest run --coverage

Test Patterns

The test suite uses several patterns for database and API testing:

Hono app.request(): Use Hono's built-in testing method rather than Supertest. This tests the full middleware stack without starting a network server.
Test headers: Use x-test-user-id andx-test-agent-id headers to simulate authenticated requests in test mode.
Session auth bypass: Set x-test-auth-type: 'session' to simulate dashboard (session) authentication, which bypasses consent checks.
Consent grants: When testing agent-authenticated requests, call grantConsent() in the beforeEach hook to grant the necessary permissions.
Serial execution: Tests run with fileParallelism: false andsingleFork: true to prevent connection pool exhaustion.

typescript

// Example test
import { describe, it, expect, beforeEach } from 'vitest';
import { app } from '../src/app';

describe('Profile API', () => {
  beforeEach(async () => {
    // Setup test user schema, seed data, etc.
  });

  it('should return the user profile', async () => {
    const res = await app.request('/v1/profile', {
      headers: {
        'x-test-user-id': 'test-user-001',
        'x-test-auth-type': 'session',
      },
    });

    expect(res.status).toBe(200);
    const body = await res.json();
    expect(body.data).toBeDefined();
    expect(body.version).toBeGreaterThan(0);
  });
});

Code Style

The project follows these conventions:

TypeScript strict mode: Both the API and dashboard use strict: true in tsconfig.json. No any types unless absolutely necessary (and documented).
ESM modules: The project uses ES modules throughout. Use import/export, notrequire/module.exports.
Naming conventions: camelCase for variables and functions, PascalCase for types/interfaces/components, snake_case for database columns and API response fields, UPPER_SNAKE_CASE for constants.
File naming: camelCase for service/utility files (e.g., profileService.ts), PascalCase for React components (e.g., Profile.tsx).
Path aliases: Use @/ alias for imports from the src directory (both API and dashboard).
Zod validation: All external inputs (request bodies, query params, MCP tool arguments) must be validated with Zod schemas before use.

Pull Request Process

We welcome contributions! Here is the process for submitting changes:

1. Branch Naming

Use descriptive branch names with a prefix indicating the type of change:

text

feat/add-export-endpoint     # New feature
fix/vector-search-threshold  # Bug fix
docs/update-api-reference    # Documentation
refactor/extract-service     # Code refactoring
test/add-graph-tests         # Test additions

2. Commit Messages

Follow conventional commit format:

text

feat: add vector collection deletion endpoint
fix: prevent deadlock in nested withUserSchema calls
docs: add self-hosting backup instructions
test: add consent system integration tests
refactor: extract embedding logic into shared utility

3. PR Requirements

Tests: All new features and bug fixes must include tests. Test coverage should not decrease.
TypeScript: No type errors. Run tsc --noEmit to verify.
All tests pass: Run npm test before submitting.
Schema changes: Any database schema changes must include a migration file created via supabase migration new.
Documentation: Update relevant documentation if the change affects the API, MCP tools, or user-facing behavior.

4. Review Process

PRs are reviewed for correctness, test coverage, code style, and alignment with the technical specification. Schema changes are reviewed by the database architect. API changes require agreement between the API builder and MCP engineer to ensure consistency between REST and MCP interfaces.

Thank you for contributing to Epitome! If you have questions, open a discussion on GitHub or reach out in the project's community channels.

Security Model Troubleshooting / FAQ