Disclaimer: This blog post is automatically generated from project documentation and technical proposals using AI assistance. The content represents our development journey and architectural decisions. Code examples are simplified illustrations and may not reflect the exact production implementation.

Table of Contents

About This Blog

Welcome to “Claude, Caroline and Me” - a development blog documenting the journey of building a modern real-time scoring system for padel matches. This blog captures the iterations, challenges, and solutions as we work together to create something functional and scalable.

The Team

Claude is the tool - the AI assistant that helps write code and solve problems.

Caroline is what I call the AI personality that collaborates with me on architecture and implementation.

Me - the human developer bringing it all together.

The Project

The Scores project is a real-time padel match scoring system built with Event Sourcing and CQRS patterns. The architecture separates writes (PostgreSQL event store) from reads (ClickHouse analytics), with NATS JetStream handling event streaming between services.

graph TB
    subgraph Frontend["Frontend Layer"]
        UI[Web UI]
        WS[WebSocket]
        SSE[Server-Sent Events]
    end

    subgraph Application["Application Layer"]
        API[API Service]
        CMD[Command Handlers]
        QRY[Query Handlers]
    end

    subgraph Storage["Storage Layer"]
        PG[(PostgreSQL<br/>Event Store)]
        CH[(ClickHouse<br/>Analytics)]
    end

    subgraph Streaming["Event Streaming"]
        NATS[NATS JetStream]
    end

    UI --> API
    WS --> API
    SSE --> API
    API --> CMD
    API --> QRY
    CMD --> PG
    QRY --> CH
    PG --> NATS
    NATS --> CH

    style Frontend fill:#e3f2fd
    style Application fill:#e8f5e9
    style Storage fill:#fff9c4
    style Streaming fill:#fce4ec

The system supports:

  • Real-time match scoring with Server-Sent Events
  • Audio streaming for voice command input
  • Advanced analytics for player performance
  • Multi-service architecture with proper domain boundaries

What We’re Building

Recent development iterations have focused on several key areas:

Security & Authentication: Implemented OAuth2 Token Exchange for securing real-time connections. The security layer includes origin validation, session-based authentication, and proper JWT signing with asymmetric cryptography.

Connection Management: Designed a connection pooling architecture to reduce the overhead of multiple WebSocket and EventSource connections per page. The proposal introduces singleton connection managers with event distribution layers for efficient resource usage.

Session Security: Implemented session key rotation using multiple keys stored securely, enabling zero-downtime key rotation while maintaining active user sessions.

Repository Pattern: Migrating from an event-driven architecture with separate evolver service to proper Domain-Driven Design with the Repository pattern. This eliminates intermediate services and ensures atomic operations through single transactions.

Infrastructure Optimization: Proposed Docker build optimizations using multi-stage builds with esbuild bundling, reducing production image sizes from approximately 944MB to 200MB (78% reduction) while maintaining full development capabilities.

Query Simplification: Identified opportunities to simplify ClickHouse queries by pre-computing common patterns, reducing query complexity by 60-80% through strategic column additions.

Recent Development Iterations

The recent work has been structured around several proposals and implementation summaries:

  1. Protocol Security - OAuth2 token exchange architecture with dedicated exchange service
  2. Connection Pooling - Singleton connection managers for WebSocket and EventSource
  3. Session Implementation - Key rotation with secure session management
  4. Origin Integration - Cross-origin request validation using modern browser APIs
  5. Repository Migration - Moving from evolver service to aggregate/repository pattern
  6. Docker Build Optimization - Multi-stage builds with esbuild bundling
  7. ClickHouse Query Simplification - Pre-computed patterns for faster analytics
  8. Promise Modernization - Adopting modern JavaScript promise features
  9. Docker Networking - Swarm networking architecture with load balancer
  10. Biometric Data Integration - Proposed real-time heart rate and accelerometer streaming

Each iteration has been documented with detailed proposals covering architecture decisions, implementation details, and migration steps.

What’s Next

The blog will continue to document development iterations as they happen. Upcoming topics include:

  • Completing the aggregate/repository migration
  • Implementing connection pooling for the web components
  • Rolling out Docker build optimizations
  • Simplifying ClickHouse queries with pre-computed columns
  • Potentially implementing biometric data integration

Stay tuned for detailed posts about each development iteration, the challenges faced, and the solutions implemented.

This blog is generated using Hugo static site generator with the PaperMod theme, automatically deployed to Firebase Hosting via GitHub Actions.