flea/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a microservices-based Telegram bot system for text monitoring and notifications. The system consists of 4 main services that communicate via RabbitMQ:

• telegram-listener: Scans open Telegram channels and chats for messages
• telegram-client: Bot interface for user interactions
• text-matcher: Matches incoming messages against user subscriptions
• users: Manages users and their preferences

Important: This repository is the parent project containing all services as git submodules. Each service (telegram-listener, telegram-client, text-matcher, users) is a separate repository added as a submodule. Git tags are created at the parent repository level, which triggers the Drone CI/CD pipeline to automatically build and publish NuGet packages with versions based on the git tag.

Architecture

The services follow a message bus pattern using RabbitMQ for async communication:

• TelegramListener publishes:
  • MessageReceived events (for new messages)
  • MessageEdited events (for edited messages)
• TextMatcher subscribes to MessageReceived and MessageEdited, stores match history in database, and publishes:
  • TextSubscriptionMatched events (for first-time matches)
  • TextSubscriptionUpdated events (for updates to previously matched messages)
• TelegramClient subscribes to both TextSubscriptionMatched and TextSubscriptionUpdated events and notifies users

Note: WTelegram sends both UpdateNewChannelMessage and UpdateEditChannelMessage for the same message. TelegramListener publishes separate events to avoid duplicate notifications downstream.

Each service follows Clean Architecture with separate projects for:

• Host (API/entry point)
• AppServices (business logic)
• Core (shared utilities)
• Api.Contracts (REST API contracts)
• Async.Api.Contracts (event contracts)
• Persistence (database layer, where applicable)
• Migrator (database migrations, where applicable)

Development Commands

Running the System

# Start all services with Docker Compose
docker-compose up

# Start individual services for development
cd telegram-client && dotnet run --project src/Nocr.TelegramClient.Host
cd telegram-listener && dotnet run --project src/Nocr.TelegramListener.Host  
cd text-matcher && dotnet run --project src/Nocr.TextMatcher.Host
cd users && dotnet run --project src/Nocr.Users.Host

Building

# Build individual services
cd <service-name> && dotnet build

# Build specific projects
dotnet build src/Nocr.<ServiceName>.Host

Testing

# Run unit tests (only text-matcher has tests currently)
cd text-matcher && dotnet test

Database Migrations

For text-matcher and users services:

# Add new migration (from service root directory)
cd text-matcher && ./src/Nocr.TextMatcher.Migrator/AddMigration.sh MyMigrationName
cd users && ./src/Nocr.Users.Migrator/AddMigration.sh MyMigrationName

# Apply migrations (handled automatically by migrator containers in docker-compose)

Configuration

📖 See CONFIGURATION.md for detailed configuration guide.

Quick Start

The system uses ASP.NET Core's layered configuration with Environment Variables having highest priority.

Configuration priority (lowest → highest):

1. appsettings.json (base settings, committed)
2. appsettings.{Environment}.json (environment-specific, some committed via .example files)
3. User Secrets (Development only)
4. Environment Variables (ALWAYS WINS)

Three Deployment Modes

1. VS Code (Local Development)

   • Copy appsettings.Development.json.example → appsettings.Development.json in each service
   • Or use environment variables in .vscode/launch.json
   • Start infrastructure: docker-compose up nocr-rabbitmq nocr-text-matcher-db nocr-users-db -d

2. Docker Compose (Local Full Stack)

   • Copy .nocr.env.example → .nocr.env in project root
   • Fill in your Telegram API credentials and Bot token
   • Run: docker-compose up

3. Kubernetes (Production)

   • Create K8s Secrets (do NOT use .nocr.env)
   • Reference secrets in deployment manifests via envFrom

Debug Mode

Enable configuration debug logging on startup:

export NOCR_DEBUG_MODE=true

This prints masked configuration values to help troubleshoot issues.

Important Notes

• ❌ Never commit secrets - use .example files as templates
• ✅ Environment variables override all appsettings files
• ✅ All services use .example files for documentation
• ✅ Docker Compose uses .nocr.env file (gitignored)

Service Ports

When running with docker-compose:

• telegram-client: 5050 (http://localhost:5050/health)
• telegram-listener: 5040 (http://localhost:5040/health)
• text-matcher: 5041 (http://localhost:5041/health)
• users: 5042 (http://localhost:5042/health)
• RabbitMQ: 5672 (AMQP), 15672 (Management UI - http://localhost:15672, admin/admin)
• MariaDB: 3316 (text-matcher), 3326 (users)

Key Technologies

• .NET 8
• ASP.NET Core Web APIs
• Entity Framework Core with MariaDB
• WTelegramClient for Telegram API
• Rebus for message bus (RabbitMQ)
• Docker & Docker Compose for containerization
• Drone CI/CD on Kubernetes

NuGet Package Management

The project uses Central Package Management (CPM) with Package Source Mapping to manage NuGet dependencies:

Package Sources

• nuget.org: All public packages (Microsoft., Serilog., etc.)
• musk (private): Internal Nocr.* contract packages

Configuration

The nuget.config file in the project root defines package source mapping:

<packageSourceMapping>
  <packageSource key="musk">
    <package pattern="Nocr.*" />
  </packageSource>
  <packageSource key="nuget.org">
    <package pattern="*" />
  </packageSource>
</packageSourceMapping>

How It Works

1. Local Development: Copy nuget.config to each submodule root when needed
2. CI/CD: Drone automatically copies nuget.config to /root/.nuget/NuGet/NuGet.Config
3. Docker Builds: Kaniko copies nuget.config to submodule root before building

This eliminates NuGet warning NU1507 and ensures consistent package resolution across all environments.

CI/CD Pipeline

📖 See _deploy/README.md for full CI/CD documentation.

The project uses Drone CI with 5 specialized pipelines:

1. Feature Validation (feature/*, fix/* branches)

Purpose: Test feature branches before merging to main

How to trigger:

# Create feature branch and push
git checkout -b feature/my-new-feature
# ... make changes ...
git add .
git commit -m "Add new feature"
git push origin feature/my-new-feature

What happens:

• Runs build + tests with Testcontainers support
• Provides fast feedback before merge
• Duration: ~3-5 minutes

2. Main Validation (main branch)

Purpose: Ensure main branch stays healthy after merge

How to trigger:

# Merge feature to main
git checkout main
git merge feature/my-new-feature
git push origin main

What happens:

• Same checks as feature validation
• Ensures main branch builds and tests pass
• Duration: ~3-5 minutes

3. Contracts-Only Publish

Purpose: Publish NuGet contracts without building Docker images (fast iteration)

How to trigger:

# Update contracts in a submodule
cd telegram-listener
# ... update Async.Api.Contracts ...
git add . && git commit -m "Add MessageEdited event"
git push

# From parent repo, tag with contracts_only marker
cd ..
git add telegram-listener
git commit -m "contracts_only:telegram_listener - Add MessageEdited event"
git tag 0.7.41
git push && git push --tags

What happens:

• Publishes only the specified service's NuGet contracts
• Skips Docker image builds
• Duration: ~2 minutes

Services: telegram_listener, text_matcher, users

4. Full Release

Purpose: Complete release - contracts + images + deployment

How to trigger:

# Make your changes, commit to main
git add .
git commit -m "Implement new feature"
git push

# Tag for full release (no special markers in commit message)
git tag v1.3.0
git push --tags

What happens:

1. Publishes all NuGet contracts (parallel)
2. Builds all Docker images with Kaniko (parallel, after contracts)
3. Deploys to Kubernetes (automatic for v* tags)

• Duration: ~8-10 minutes

5. Deploy-Only

Purpose: Deploy existing images without rebuilding (rollbacks, hotfixes)

How to trigger:

# Deploy already-built images (e.g., rollback to previous version)
git commit --allow-empty -m "deploy_only: Rollback to v1.2.9"
git tag deploy-v1.2.9
git push && git push --tags

# Or deploy latest images
git commit --allow-empty -m "deploy_only: Deploy latest"
git tag deploy-latest
git push && git push --tags

What happens:

• Skips building entirely
• Deploys specified tag's images (or latest)
• Duration: ~1 minute

Common CI/CD Workflows

Test a Feature Branch

git checkout -b feature/add-logging
# ... make changes ...
git add . && git commit -m "Add structured logging"
git push origin feature/add-logging
# ✅ Drone runs feature-validation pipeline

Publish Contracts After API Changes

cd text-matcher
# Update Nocr.TextMatcher.Async.Api.Contracts
git add . && git commit -m "Add UserDeleted event"
git push

cd ..
git add text-matcher
git commit -m "contracts_only:text_matcher - Add UserDeleted event"
git tag 0.8.5
git push && git push --tags
# ✅ Drone publishes text-matcher contracts to NuGet

Full Release Workflow

# Work on main branch
git add .
git commit -m "Implement payment processing"
git push
# ✅ Drone runs main-validation

# Tag for release
git tag v2.0.0
git push --tags
# ✅ Drone runs full-release pipeline:
#    1. Publishes all contracts
#    2. Builds all Docker images
#    3. Deploys to Kubernetes

Emergency Rollback

# Rollback to last known good version
git commit --allow-empty -m "deploy_only: Emergency rollback to v1.9.5"
git tag rollback-v1.9.5
git push && git push --tags
# ✅ Drone deploys v1.9.5 images immediately (~1 minute)

Deployment Scripts

Located in _deploy/scripts/:

• deploy.sh - Deploy services to Kubernetes with health checks
• rollback.sh - Rollback deployments to previous version
• health-check.sh - Check health of all services

Key Optimizations

• Shared NuGet cache across pipeline steps (~60% faster builds)
• Parallel execution for independent operations
• Proper dependency order: Contracts → Images → Deploy
• Kaniko layer caching for faster Docker builds
• Docker-in-Docker support for Testcontainers in tests