Tel-Insights Development Assistant

Expert assistant for working with the Tel-Insights microservices architecture - a Telegram monitoring and AI analysis platform with async message queue communication.

Architecture Understanding

Tel-Insights uses a **microservices architecture** with **RabbitMQ** for async communication:

```

Aggregator → RabbitMQ → AI Analysis → PostgreSQL

↓ ↓ ↑

PostgreSQL Smart Analysis ←──┘

↑ ↓

Alerting ←─────────────── MCP Tools

```

Core Services

1. **Aggregator** (`src/aggregator/`): Telegram client using Telethon, monitors channels, publishes to queue

2. **AI Analysis** (`src/ai_analysis/`): Queue consumer, processes messages with Gemini LLM, stores metadata

3. **Smart Analysis** (`src/smart_analysis/`): MCP server, frequency-based alerts, news summarization

4. **Alerting** (`src/alerting/`): Telegram bot using python-telegram-bot (TODO: not yet implemented)

Shared Components

Development Workflow

1. Running Services

Always use the service runner for starting services:

```bash

Start individual services

python run_service.py aggregator # Telegram message collector

python run_service.py ai-analysis # AI processing with Gemini

python run_service.py smart-analysis # MCP server and alerts

python run_service.py alerting # Telegram bot interface

Alternative platform-specific scripts

./run_service.sh <service> # Linux/macOS

run_service.bat <service> # Windows

```

2. Testing

Run tests using pytest with appropriate markers:

```bash

Run all tests

pytest

Run by category

pytest -m unit

pytest -m integration

pytest -m e2e

With coverage reporting

pytest --cov=src --cov-report=html

Single test file

pytest tests/unit/test_models.py

```

**Test Structure:**

3. Database Management

Use Alembic for database migrations:

```bash

Apply all pending migrations

alembic upgrade head

Create new migration (auto-generate from model changes)

alembic revision --autogenerate -m "Description of changes"

Rollback last migration

alembic downgrade -1

```

4. Code Quality

Always format and lint code before committing:

```bash

Format code (Black with 88-character line length)

black src/

isort src/ # Black profile

Lint and type check

flake8 src/

mypy src/

```

**Important:** Use these exact commands. Black is configured for 88-character line length and isort uses Black profile.

Key Technical Requirements

Service Communication

AI Metadata Structure

Messages store rich AI analysis in PostgreSQL JSONB (GIN indexed):

```json

{

"summary": "Brief message summary",

"topics": ["technology", "AI"],

"sentiment": "positive",

"entities": {"organizations": ["OpenAI"], "locations": ["SF"]},

"keywords": ["AI", "breakthrough"],

"confidence_score": 0.95

}

```

MCP Server

Smart Analysis runs an MCP server on port 8003 with tools:

Environment Configuration

Copy `config.env.template` to `.env` and configure:

Database Schema

Core tables:

Critical Dependencies

Development Guidelines

1. **Before making changes**: Read relevant service code in `src/{service_name}/`

2. **Service modifications**: Understand the async message flow through RabbitMQ

3. **Database changes**: Create Alembic migration with `--autogenerate`

4. **Adding features**: Test with unit tests first, then integration tests

5. **Code style**: Always run `black` and `isort` before committing

6. **Service testing**: Start dependencies (PostgreSQL, RabbitMQ) before running services

7. **AI metadata**: Follow the established JSONB structure for consistency

8. **MCP tools**: Add new tools to `src/smart_analysis/mcp_server.py`

Common Tasks

Adding a new monitored channel

1. Add channel to `MONITORED_CHANNELS` in `.env`

2. Restart aggregator service

3. Channel automatically added to database on first message

Modifying AI analysis

1. Edit `src/ai_analysis/gemini_processor.py`

2. Update AI metadata structure if needed

3. Run unit tests: `pytest tests/unit/test_ai_analysis.py`

4. Test with integration: `pytest -m integration`

Creating new MCP tool

1. Add tool function to `src/smart_analysis/mcp_server.py`

2. Use FastMCP decorators for tool registration

3. Test via MCP client or Claude Desktop integration

Database schema changes

1. Modify models in `src/shared/models.py`

2. Generate migration: `alembic revision --autogenerate -m "description"`

3. Review generated migration in `alembic/versions/`

4. Apply: `alembic upgrade head`

Constraints