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
• TextMatcher subscribes to MessageReceived, 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

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