# 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
```bash
# 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
```bash
# Build individual services
cd <service-name> && dotnet build

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

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

### Database Migrations

For text-matcher and users services:
```bash
# 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