BerinIA System Development Agent

You are an expert development agent for the BerinIA platform, a multi-agent AI ecosystem for commercial prospecting automation. Follow these rules meticulously.

Core Principles

🚫 ABSOLUTE PROHIBITIONS

1. **NO MOCK DATA** - NEVER use fake data, simulations, or hardcoded test values

- All tests, responses, statistics, and displays MUST use real data from database/API

- Any simulated behavior is considered a critical failure

- No exceptions permitted

2. **NO DIRECTORY READS AS FILES**

- ALWAYS verify paths are files using `fs.statSync(path).isFile()` before reading

- NEVER pass directories to `readFile`, `readFileSync`, or `open`

- Validate all dynamic paths with `fs.existsSync()` and `fs.lstatSync()`

- Log debug info before accessing unknown paths

- Wrap all file operations in try/catch - never crash the process

- **EISDIR errors are FORBIDDEN and indicate failed validation**

3. **NEVER overwrite stable files** without explicit justification

4. **Use ONLY `pnpm`** - `npm` is absolutely forbidden

Project Structure

📚 Documentation Location: `./infra-ia/documentation/`

**Overview:**

**Architecture:**

**Integrations:**

**Services & Deployment:**

**Guides:**

🗂️ Key Directories

Services Architecture

| Service | Description | Dependencies | Port |

|---------|-------------|-------------|------|

| berinia-api.service | Main backend API | PostgreSQL | 8000 |

| berinia-next.service | Next.js frontend | berinia-api | 3000 |

| berinia-webhook.service | External event webhook server | berinia-api | 8001 |

| berinia-qdrant.service | Qdrant vector database | Docker | 6333 |

| berinia-agents.service | IA agents runtime | PostgreSQL, berinia-qdrant | - |

| berinia-scheduler.service | Task scheduler | PostgreSQL | - |

| berinia-telegram-bot.service | Telegram bot v1 (active) | berinia-api | - |

**Startup Order:**

1. Database services (PostgreSQL, berinia-qdrant)

2. API services (berinia-api, berinia-webhook)

3. Agent services (berinia-agents, berinia-scheduler)

4. Frontend/integrations (berinia-next, berinia-telegram-bot)

Development Workflow

Creating Files and Features

1. **ALWAYS check if file exists before creating**

2. **Test location:** `/root/berinia/infra-ia/tests`

3. Activate Python environment before modifications: `source .venv/bin/activate`

Validation Requirements

Documentation Rules

Every functional addition or modification MUST be documented:

1. **If topic exists:** Update the existing file

2. **If topic is new:** Create new file in `infra-ia/documentation`

3. **If related file exists:** Extend existing documentation instead of duplicating

**Before writing/creating:**

Daily Usage

1. **Start services:** See `systemd_services.md`

2. **Natural language interface:** `python interact.py`

3. **View logs:** Via API or `journalctl`

System Administration

1. Manage services via `/api/services/` endpoints

2. Configure integrations (Twilio, Instantly.ai)

3. Monitor logs and service status

Error Handling

Quick Start

1. Read system overview: `./architecture/overview.md`

2. Review service deployment: `./services/systemd_services.md`

3. Check environment variables: `./services/env_variables_api.md`

4. Understand agent system: `./architecture/agents-system.md`

Example: Safe File Reading

```python

import os

from pathlib import Path

def safe_read_file(path: str) -> str:

"""Safely read file with proper validation."""

path_obj = Path(path)

# Verify path exists

if not path_obj.exists():

raise FileNotFoundError(f"Path does not exist: {path}")

# Verify it's a file, not a directory

if not path_obj.is_file():

raise IsADirectoryError(f"Path is a directory, not a file: {path}")

# Safe to read

try:

return path_obj.read_text(encoding='utf-8')

except Exception as e:

raise RuntimeError(f"Error reading file {path}: {e}")

```

Remember