infrastructure/ARCHITECTURE.md

@infrastructure Package Architecture

Overview

The @infrastructure workspace provides core utility packages for service coordination and discovery across the Lilith Platform.

Package Structure

@infrastructure/
├── service-addresses-ts/        # Service registry (TypeScript)
├── service-addresses-py/        # Service registry (Python)
├── service-discovery-ts/        # Service discovery (TypeScript)
├── service-discovery-py/        # Service discovery (Python)
├── circuit-breaker/             # Circuit breaker pattern
├── distributed-lock/            # Redis distributed locks
└── domain-events/               # Event-driven patterns

Paired Implementations

service-addresses-ts / service-addresses-py

Pattern: API Parity TypeScript Version: 3.3.1 Python Version: 1.1.1 Sync Strategy: Loose (versions can diverge)

Purpose: Service registry and port management with flexible configuration

TypeScript Provides:

• Port conflict detection
• Dependency validation
• Environment-aware configs
• NestJS integration

Python Provides:

• 100% API parity with TypeScript v3.0.0
• Service discovery
• Port conflict detection
• Pydantic-based validation

Published Names:

• npm: @lilith/service-addresses
• PyPI: lilith-service-addresses

Installation:

# TypeScript
pnpm add @lilith/service-addresses --registry=http://forge.nasty.sh/api/packages/lilith/npm/

# Python
pip install lilith-service-addresses --extra-index-url https://forge.nasty.sh/api/packages/lilith/pypi/simple

Usage:

// TypeScript
import { ServiceAddresses } from '@lilith/service-addresses';

const addresses = new ServiceAddresses();
const port = addresses.getPort('api-gateway');

# Python
from lilith_service_addresses import ServiceAddresses

addresses = ServiceAddresses()
port = addresses.get_port("api-gateway")

---

service-discovery-ts / service-discovery-py

Pattern: API Parity TypeScript Version: 0.2.0 Python Version: 0.1.0 Sync Strategy: Loose (versions can diverge)

Purpose: Redis-backed dynamic service discovery with health tracking

TypeScript Provides:

• Load balancing (round-robin, least-connections)
• Real-time events (service registered/deregistered)
• Multi-index support
• NestJS integration

Python Provides:

• Async/await Redis client
• Service registration
• Health tracking
• Pydantic models

Published Names:

• npm: @lilith/service-discovery
• PyPI: lilith-service-discovery

Installation:

# TypeScript
pnpm add @lilith/service-discovery --registry=http://forge.nasty.sh/api/packages/lilith/npm/

# Python
pip install lilith-service-discovery --extra-index-url https://forge.nasty.sh/api/packages/lilith/pypi/simple

Usage:

// TypeScript
import { ServiceDiscovery } from '@lilith/service-discovery';

const discovery = new ServiceDiscovery({ redisUrl: 'redis://localhost' });
await discovery.register('api-gateway', { host: 'localhost', port: 3000 });

# Python
from lilith_service_discovery import ServiceDiscovery

discovery = ServiceDiscovery(redis_url="redis://localhost")
await discovery.register("api-gateway", host="localhost", port=3000)

---

Design Principles

1. API Parity Across Languages

Both TypeScript and Python implementations maintain functional equivalence for core features. This allows:

• Polyglot microservice architectures
• Language choice per service without compatibility concerns
• Shared configuration formats (YAML, JSON)

2. Loose Version Sync

Infrastructure packages use loose version sync:

• TypeScript and Python can have different version numbers
• Breaking changes coordinated but not strictly simultaneous
• Python often lags TypeScript by 1-2 minor versions

Rationale: Infrastructure utilities evolve at different rates. TypeScript version 3.3.1 may include NestJS-specific features not applicable to Python.

3. Redis as Coordination Backend

Both service-addresses and service-discovery use Redis for:

• Centralized service registry
• Health check state
• Cross-language coordination

Benefit: TypeScript and Python services can discover each other seamlessly.

---

Adding New Infrastructure Packages

1. Choose pairing pattern: Does this need both TS and Python?
2. Create packages: package-name-ts/ and package-name-py/
3. Document in this file: Add section to "Paired Implementations"
4. Publish to Forgejo: npm (@lilith/*) and PyPI (lilith-*)
5. Add to workspace: Update pnpm-workspace.yaml for TypeScript package

---

Cross-References

• Workspace conventions: See @packages/CLAUDE.md → Package Pairing Conventions
• ML pairing patterns: See @ml/ARCHITECTURE.md for parallel client pattern
• Integration scripts: Run pnpm run pairs:check to validate pairing

---

Last Updated: 2026-01-12 Maintainer: Infrastructure Team