Monorepo Structure

Understanding the Data Pod codebase

Overview

Data Pod uses a monorepo with pnpm workspaces.

synap-backend/
├── apps/          # Deployable applications
├── packages/      # Reusable libraries
└── services/      # Example services

Key principle: Packages are building blocks, apps combine them.

Apps (Deployable)

apps/api/

Main Data Pod API server.

What it does:

• Serves tRPC endpoints
• Handles webhooks
• Provides SSE for real-time
• Runs event processors

Key files:

• src/index.ts - Server setup
• src/webhooks/ - Webhook handlers

Run locally:

cd apps/api
pnpm dev

Packages (Libraries)

packages/api/

tRPC router definitions and business logic.

Contains:

• src/routers/ - API endpoints
• src/event-handlers/ - Event processors
• src/plugins/ - Plugin system

Example:

// packages/api/src/routers/notes.ts
export const notesRouter = router({ ... });

packages/database/

Database schema and migrations.

Contains:

• src/schema/ - Drizzle table definitions
• migrations/ - SQL migration files
• src/projectors/ - Event sourcing projections

Example:

// packages/database/src/schema/notes.ts
export const notes = pgTable('notes', { ... });

packages/events/

Event type definitions.

Contains:

• src/domain-events.ts - Typed events
• src/publisher.ts - Event publishing
• src/payloads.ts - Zod schemas

Example:

// packages/events/src/domain-events.ts
export type NoteCreatedEvent = BaseEvent<...>;

packages/client/

TypeScript SDK for frontends.

Contains:

• src/index.ts - Main client class
• src/facades/ - High-level APIs
• Auto-generated from packages/api

Example:

const client = new SynapClient({ url: '...' });
await client.notes.create({ content: '...' });

packages/core/

Shared utilities.

Contains:

• Config management
• Logging
• Utilities

Services (Examples)

services/intelligence/

Example intelligence service (optional).

Shows how to build a remote service that integrates with Data Pod.

Package Dependencies

apps/api
  ├─→ packages/api
  ├─→ packages/database
  ├─→ packages/events
  └─→ packages/core

packages/api
  ├─→ packages/database
  ├─→ packages/events
  └─→ packages/core

packages/client
  └─→ packages/api (types only)

Rule: Packages can depend on other packages, apps depend on packages.

Building Order

When changing code, build in dependency order:

# 1. Database (no dependencies)
cd packages/database && pnpm build
 
# 2. Events (no dependencies)
cd ../events && pnpm build
 
# 3. API (depends on database, events)
cd ../api && pnpm build
 
# 4. Client (depends on API types)
cd ../client && pnpm build
 
# 5. Apps (depend on everything)
cd ../../apps/api && pnpm build

Or build all:

pnpm build  # From root, builds in correct order

Common File Patterns

Adding a Router

1. Create in packages/api/src/routers/
2. Register in packages/api/src/index.ts
3. Client automatically gets types

Adding Schema

1. Create in packages/database/src/schema/
2. Export from packages/database/src/schema/index.ts
3. Create migration in packages/database/migrations/

Adding Events

1. Define in packages/events/src/domain-events.ts
2. Add builder in packages/events/src/publisher.ts
3. Export from packages/events/src/index.ts

Development Tips

Hot reload: Apps auto-reload on changes

cd apps/api && pnpm dev  # Watches for changes

Type checking: TypeScript checks across packages

pnpm typecheck  # Check all packages

Linting: ESLint + Prettier

pnpm lint
pnpm format

Next Steps

• Add router → Router Development
• Change schema → Database Migrations
• Work with events → Event System