137 lines
4.9 KiB
Markdown
137 lines
4.9 KiB
Markdown
# 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
|
|
|
|
**📖 See [CONFIGURATION.md](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:
|
|
```bash
|
|
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 |