---

name: tzurot-architecture description: Contains MANDATORY microservices architecture rules for Tzurot v3. MUST be consulted before creating new services or deciding where code belongs. Covers service boundaries, dependencies, and anti-patterns from v2. lastUpdated: '2026-01-21'

Tzurot v3 Architecture

Use this skill when: Adding new features, deciding where code belongs, designing system interactions, or refactoring service boundaries.

Quick Reference

CopyDiscord User
    ↓
bot-client (Discord.js)
    ↓ HTTP
api-gateway (Express + BullMQ)
    ↓ Redis Queue
ai-worker (AI + pgvector)
    ↓
OpenRouter/Gemini API

Core Principles

1. Simple, clean classes - No DDD over-engineering (learned from v2)
2. Clear service boundaries - Each service has single responsibility
3. No circular dependencies - Services can't import from each other
4. Shared code in common-types - Cross-service types, utils, services
5. Constructor injection - Simple dependency passing, no DI containers

Three Microservices

Where to Put New Code

Autocomplete Utilities (CRITICAL)

ALWAYS check for existing utilities before writing autocomplete handlers.

Available in bot-client/src/utils/autocomplete/:

Copy// ✅ GOOD - Delegate to shared utility
import { handlePersonalityAutocomplete } from '../../utils/autocomplete/personalityAutocomplete.js';

await handlePersonalityAutocomplete(interaction, {
  optionName: 'personality',
  showVisibility: true,
  ownedOnly: false,
});

// ❌ BAD - Duplicating 50+ lines of autocomplete logic

Error Message Patterns

Copy// ✅ Gateway - clean for programmatic use
sendError(res, ErrorResponses.notFound('Persona'));

// ✅ Bot - emoji for users
await interaction.editReply({ content: '❌ Profile not found.' });

Anti-Patterns from v2 (DON'T DO)

Copy// ❌ v2 - Container hell
container.bind('PersonalityService').to(PersonalityService);
const service = container.get('PersonalityService');

// ✅ v3 - Simple
const service = new PersonalityService(prisma);

Dependency Injection

Copy// ✅ GOOD - Simple constructor injection
class MyService {
  constructor(
    private prisma: PrismaClient,
    private redis: Redis
  ) {}
}

const service = new MyService(prisma, redis);

When to Extract a Service

Extract when:

• Shared across multiple microservices → common-types
• Complex business logic
• Stateful operations
• Easier testability needed

Keep inline when:

• Used in one place only
• Stateless utility function
• Very simple logic

Complexity Signals (ESLint Warnings)

ESLint warnings indicate when to refactor:

📚 See: tzurot-code-quality skill for refactoring patterns

Database Access

Direct Prisma in services - No repository pattern

Copy// ✅ Direct Prisma
async getPersonality(id: string) {
  return this.prisma.personality.findUnique({ where: { id } });
}

// ❌ Generic repository
interface PersonalityRepository {
  findById(id: string): Promise<Personality>;
}

Configuration

• Environment variables: Secrets (tokens, DB URLs)
• common-types constants: Application config (timeouts, limits)

Copyimport { TIMEOUTS, RETRY_CONFIG } from '@tzurot/common-types';
const timeout = TIMEOUTS.LLM_INVOCATION;

Related Skills

• tzurot-code-quality - Refactoring patterns for complexity
• tzurot-async-flow - BullMQ job patterns
• tzurot-db-vector - Database patterns
• tzurot-types - Type definitions
• tzurot-council-mcp - Major design decisions

References

• Full architecture: CLAUDE.md#architecture
• Project structure: CLAUDE.md#project-structure
• Architecture decisions: docs/architecture/ARCHITECTURE_DECISIONS.md