roa2web-service-auto/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

🚀 Project Overview

ROA2WEB - Modern ERP Reports Application with FastAPI backend, Vue.js frontend, and Telegram bot interface using microservices architecture.

Active Branch: v2-roa2web-fastapi Main Branch: main (use for PRs) Working Directory: Repository root

Quick Reference: See README.md for complete setup, commands, deployment, and testing instructions.

---

🏗️ Architecture

Microservices Structure

.
├── shared/                    # Shared components (DB pool, auth, utils)
├── reports-app/
│   ├── backend/              # FastAPI API (port 8001)
│   ├── frontend/             # Vue.js 3 UI (port 3000-3005)
│   └── telegram-bot/         # Telegram bot (port 8002 internal)
├── docs/                     # Architecture & style guides
├── deployment/               # Production deployment scripts
└── ssh-tunnel/              # SSH tunnel for Oracle DB access

Key Architectural Decisions

• Shared Database Pool: Singleton OraclePool in shared/database/oracle_pool.py (python-oracledb with connection pooling)
• Centralized Auth: JWT-based auth in shared/auth/ with middleware auto-injecting request.state.user
• SSH Tunnel: Required for Oracle DB connections (development/Linux) - see Database Setup
• FastAPI Structure: Routers in backend/app/routers/, schemas in backend/app/schemas/, Oracle stored procedures (no ORM)
• Telegram Bot: Standalone SQLite database for bot data, communicates with backend via HTTP API

---

🗄️ Database Setup

Schema: CONTAFIN_ORACLE (authentication and user management) Connection: SSH tunnel required (Oracle on remote network)

SSH Tunnel (Development/Linux)

./ssh_tunnel.sh start     # localhost:1526 → remote:1521
./ssh_tunnel.sh status    # Check tunnel
./ssh_tunnel.sh stop      # Stop tunnel

IMPORTANT: Always ensure SSH tunnel is running before starting backend services.

Environment Variables (reports-app/backend/.env)

# Oracle Database (through SSH tunnel)
ORACLE_USER=CONTAFIN_ORACLE
ORACLE_PASSWORD=your_password
ORACLE_HOST=localhost
ORACLE_PORT=1526
ORACLE_SID=ROA

# JWT Authentication
JWT_SECRET_KEY=your_secret_key
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=30

# Telegram Bot Integration
TELEGRAM_BOT_INTERNAL_API=http://localhost:8002

Windows Production: Direct Oracle connection, no SSH tunnel required. Ensure TELEGRAM_BOT_INTERNAL_API is set for auth code management.

---

🔑 Authentication Flow

1. Login: POST /api/auth/login → calls pack_drepturi.verificautilizator(username, password)
2. Token: JWT includes username, user_id, companies[], permissions[], exp, iat, type
3. Middleware: AuthenticationMiddleware in shared/auth/middleware.py validates tokens, injects user
4. Protected Routes: All routes except excluded_paths require valid JWT

Key Files:

• shared/auth/middleware.py - FastAPI middleware with rate limiting (5 req/5 min)
• shared/auth/jwt_handler.py - Token creation/validation
• reports-app/backend/app/main.py - Auth router inline definition

---

📝 Common Development Tasks

Adding a New API Endpoint

1. Create router in reports-app/backend/app/routers/your_router.py
2. Define Pydantic schemas in app/schemas/
3. Use oracle_pool.get_connection() context manager for DB queries
4. Register router in app/main.py: app.include_router(your_router, prefix="/api/your_prefix")

Example:

async with oracle_pool.get_connection() as connection:
    with connection.cursor() as cursor:
        cursor.execute("""
            SELECT pack_name.procedure_name(:param1, :param2)
            FROM DUAL
        """, {'param1': value1, 'param2': value2})
        result = cursor.fetchone()

Adding a New Frontend Page/Component

IMPORTANT: Follow the established CSS architecture and design system.

Before writing ANY CSS: Read docs/ONBOARDING_CSS.md (5-minute quick start) → See "Documentation Index" below for complete guide list.

Golden Rules:

• ✅ Use global patterns first (.roa-card, .roa-metric, .roa-badge-*) - check CSS_PATTERNS.md
• ✅ Use design tokens (var(--color-primary)) not hardcoded values (#2563eb)
• ❌ Never use :deep() in components (use src/assets/css/vendor/ for PrimeVue overrides)
• ❌ Never duplicate CSS (write once, use everywhere)

Adding a New Telegram Bot Command

IMPORTANT: Follow established command patterns and formatting.

Before coding: Read reports-app/telegram-bot/TELEGRAM_COMMANDS.md for command patterns → See "Documentation Index" for complete guides.

Standard Pattern (add handler in app/bot/handlers.py):

async def your_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    telegram_id = update.effective_user.id

    # 1. Check authentication (use helpers.py)
    user = await get_user_by_telegram_id(telegram_id)
    if not user:
        await update.message.reply_text("⚠️ Account not linked. Use /start with code.")
        return

    # 2. Check active company (use session.py)
    active_company = await get_active_company(telegram_id)
    if not active_company:
        await update.message.reply_text("⚠️ Select company first: /selectcompany")
        return

    # 3. Call backend API (use api/client.py)
    # 4. Format response (use formatters.py)
    # 5. Add tests + update MANUAL_TESTING_CHECKLIST.md

Adding Shared Functionality

1. Place in shared/{database|auth|utils}/
2. Import using sys.path.append() pattern (see backend/app/main.py:21)
3. Add tests in shared/tests/

Frontend API Integration

// Store pattern (src/stores/yourStore.js)
import axios from 'axios';

const api = axios.create({
  baseURL: 'http://localhost:8001/api',
  headers: { 'Authorization': `Bearer ${token}` }
});

const response = await api.get('/endpoint');

---

🔒 Security

• Git Hooks: Security scanning in security/install_hooks.sh
• Environment Files: Never commit .env (use .env.example as template)
• SSH Keys: In ssh-tunnel/secrets/ (gitignored)
• JWT Secrets: Generate strong secrets for production
• Rate Limiting: Built into auth middleware (5 requests per 5 minutes)

---

📚 Documentation Index

Quick Start & Commands

→ README.md - Project overview, setup, development commands, testing, deployment

Architecture & Planning

• docs/ARCHITECTURE_SCHEMA.md - Architecture diagrams and schemas
• docs/MICROSERVICES_GUIDE.md - Microservices architecture details
• DEVELOPMENT_BLUEPRINT.md - Detailed development plan

Frontend Development

• docs/ONBOARDING_CSS.md - CSS system quick start (START HERE for new components)
• docs/CSS_PATTERNS.md - Complete CSS patterns library (cards, forms, buttons, etc.)
• docs/DESIGN_TOKENS.md - Design tokens (colors, spacing, typography)
• docs/STYLING_GUIDELINES.md - CSS best practices and conventions
• docs/COMPONENT_STYLING.md - Component-specific styling guide
• docs/FORM_TEMPLATE.md - Standardized form template
• reports-app/frontend/README.md - Frontend architecture and setup
• reports-app/frontend/tests/README.md - Playwright E2E testing guide

Backend Development

• reports-app/backend/README.md - Backend architecture and API details
• API endpoints documented in README.md (Authentication, Companies, Dashboard, Invoices, Treasury, Telegram)

Telegram Bot Development

• reports-app/telegram-bot/README.md - Complete bot architecture and development guide (START HERE)
• reports-app/telegram-bot/TELEGRAM_COMMANDS.md - Command reference and patterns
• tests/MANUAL_TESTING_CHECKLIST.md - Manual testing procedures

Deployment

• DEPLOYMENT_GUIDE.md - Production deployment (Linux/Docker & Windows/IIS)
• deployment/windows/README.md - Windows deployment quick start
• deployment/windows/docs/WINDOWS_DEPLOYMENT.md - Complete Windows guide
• deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md - Bot troubleshooting

Troubleshooting

→ README.md - Common issues (SSH tunnel, backend, frontend, database) → Backend: Check .env, SSH tunnel status, port 8001 availability → Frontend: Clear node_modules, check Node.js version (16+), Vite auto-ports → Database: Verify SSH tunnel, Oracle listener, credentials, test /health

---

🔧 Tech Stack

Backend: FastAPI, python-oracledb, JWT (PyJWT), Pydantic, pytest Frontend: Vue.js 3 (Composition API), PrimeVue, Pinia, Vite, Axios, Chart.js, Playwright Telegram Bot: python-telegram-bot, SQLite + aiosqlite, httpx, FastAPI (internal), pytest Infrastructure: Oracle Database, SSH Tunnel, Nginx (Linux prod), Docker (Linux prod), IIS + NSSM (Windows prod)

---

For detailed information on any topic, always check the Documentation Index above first.