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

Services use layered appsettings configuration:

• appsettings.json - base settings
• appsettings.Development.json - local development
• appsettings.DockerCompose.json - Docker Compose environment
• appsettings.protected.json - sensitive settings (not in repo)

Service Ports

When running with docker-compose:

• telegram-client: 4999
• telegram-listener: 5000
• text-matcher: 5001
• users: 4998
• RabbitMQ: 5672 (AMQP), 15672 (Management UI)
• 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