33GOD Service Developer

Expert guide for onboarding new microservices into the 33GOD event-driven ecosystem.

Core Principles

Services in 33GOD are:

• •Passive Consumers: Sleep until relevant events arrive on Bloodbank (RabbitMQ)
• •Single Responsibility: Do one thing well (e.g., "Process Transcripts", "Calculate Costs")
• •Stateless: Store state in Vault (filesystem) or database, not in memory
• •Event-Driven: React to events rather than being called directly

Architecture Context

33GOD uses Bloodbank (RabbitMQ topic exchange) as its event bus. All services:

• •Subscribe to specific routing keys via durable queues
• •Receive EventEnvelope-wrapped messages
• •Publish events back to Bloodbank for other services

Registry: /home/delorenj/code/33GOD/services/registry.yaml is the single source of truth for:

• •Service definitions and metadata
• •Event routing mappings
• •Service topology layers

Service Development Workflow

Phase 1: Planning & Registration

1. •

   Define the service purpose

   • •What single responsibility does it serve?
   • •What events trigger it?
   • •What events does it produce?
2. •

   Register in registry.yaml

   • •Add service entry under services
   • •Define queue name and routing keys
   • •Add to event_subscriptions mapping
   • •Place in appropriate topology layer

See references/registry_guide.md for registry schema and examples.

Phase 2: Implementation

1. •

   Scaffold from template

   bash

   cd /home/delorenj/code/33GOD/services
   cp -r templates/generic-consumer/{{cookiecutter.service_slug}} ./my-new-service
   

2. •

   Implement FastStream consumer

   • •Use FastStream with RabbitBroker (ADR-0002 pattern)
   • •Unwrap EventEnvelope in handler
   • •Use Pydantic models for payload validation

See references/faststream_patterns.md for implementation patterns.

Phase 3: Configuration & Dependencies

1. •

   Update pyproject.toml

   • •Add bloodbank as local dependency
   • •Include any service-specific dependencies
2. •

   Configure environment

   • •Define settings in src/config.py
   • •Use Pydantic BaseSettings
3. •

   Docker setup

   • •Update Dockerfile if needed
   • •Ensure bloodbank volume mount for local dev

Phase 4: Testing & Deployment

1. •

   Write tests

   • •Create tests/test_consumer.py
   • •Mock EventEnvelope and payload
   • •Test handler logic in isolation
2. •

   Local testing

   bash

   cd services/my-new-service
   uv run pytest
   

3. •

   Run service

   bash

   uv run faststream run src.consumer:app
   

Reference Files

Detailed guides for specific aspects:

• •registry_guide.md: Registry schema, examples, topology layers
• •faststream_patterns.md: FastStream implementation patterns, EventEnvelope handling
• •testing_guide.md: Testing strategies, mocking patterns
• •deployment_guide.md: Docker, environment configuration, running services

Quick Reference

Common routing key patterns:

• •domain.event.action (e.g., fireflies.transcript.ready)
• •# wildcard for all events (infrastructure services only)
• •Hierarchical namespacing (e.g., theboard.meeting.*)

Service types:

• •event-consumer: Subscribes to events, performs work
• •event-producer: Produces events (often FastAPI services)
• •hybrid: Both consumer and producer

Status values:

• •active: Running in production
• •planned: Defined but not implemented
• •deprecated: Being phased out