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 and Vue.js frontend using microservices architecture.

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

🏗️ Architecture

Microservices Structure

.
├── shared/                    # Shared components across microservices
│   ├── database/             # Oracle connection pool (singleton pattern)
│   ├── auth/                 # JWT authentication & middleware
│   └── utils/                # Common utilities
├── reports-app/              # Main reports application
│   ├── backend/              # FastAPI API (port 8001)
│   ├── frontend/             # Vue.js 3 UI (Vite dev server, port 3000-3005)
│   └── telegram-bot/         # Telegram bot frontend (port 8002 internal API)
├── nginx/                    # Reverse proxy & load balancer
└── ssh-tunnel/              # SSH tunnel for Oracle DB access

Key Architectural Decisions

• Shared Database Connection Pool: Singleton OraclePool class in shared/database/oracle_pool.py is shared across all microservices. Uses python-oracledb with connection pooling.
• Centralized Authentication: JWT-based auth in shared/auth/ with middleware that auto-injects user data into request.state.
• SSH Tunnel Requirement: All Oracle DB connections go through an SSH tunnel to the remote server (see Database Setup below).
• FastAPI Structure: Routers in backend/app/routers/, schemas in backend/app/schemas/, no traditional models (Oracle stored procedures used instead).
• Telegram Bot Frontend: Alternative command-based interface for Telegram. Uses standalone SQLite database for Telegram-specific data (auth codes, sessions) and communicates with backend via HTTP API.

🗄️ Database Setup

Schema: CONTAFIN_ORACLE - Used for authentication and user management Connection Method: SSH tunnel required (Oracle DB is on remote network)

SSH Tunnel Management

./ssh_tunnel.sh start     # Start tunnel (localhost:1526 -> remote:1521)
./ssh_tunnel.sh stop      # Stop tunnel
./ssh_tunnel.sh status    # Check tunnel status
./ssh_tunnel.sh restart   # Restart tunnel

SSH Configuration:

• Remote Server: 83.103.197.79:22122
• User: roa2web
• SSH Key: ssh-tunnel/secrets/roa_oracle_server
• Local Port: 1526
• Remote Oracle: 10.0.20.36:1521

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

Environment Variables

Located in 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

IMPORTANT for Windows Deployment: Ensure TELEGRAM_BOT_INTERNAL_API is set in backend .env file. This allows the backend to communicate with the Telegram bot's internal API for auth code management. See deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md for diagnostics.

🛠️ Development Commands

Quick Start (All Services)

./start-dev.sh        # Starts SSH tunnel, backend, and frontend
./start-dev.sh stop   # Stops all ROA2WEB services
./start-dev.sh help   # Show help

This script manages:

• SSH tunnel (Oracle DB connection)
• Backend (FastAPI on port 8001)
• Frontend (Vue.js/Vite on port 3000-3005)

Backend (FastAPI)

cd reports-app/backend/

# Create virtual environment (first time only)
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

# API Documentation (when running)
# http://localhost:8001/docs          # Swagger UI
# http://localhost:8001/redoc         # ReDoc
# http://localhost:8001/health        # Health check endpoint

Frontend (Vue.js + Vite)

cd reports-app/frontend/

# Install dependencies
npm install

# Run development server (Vite will auto-assign port 3000-3005)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint and format
npm run lint
npm run format

Testing

Backend Tests (Shared Components)

cd shared/
python -m pytest -v                    # All tests
python -m pytest tests/test_auth.py -v # Specific test file

Frontend E2E Tests (Playwright)

cd reports-app/frontend/

# Run all tests (headless)
npm run test:e2e

# Run with browser UI visible
npm run test:e2e:headed

# Debug mode with step-through
npm run test:e2e:debug

# Interactive UI mode
npm run test:e2e:ui

# View test report
npm run test:e2e:report

Frontend Test Structure:

• Uses Page Object Model pattern
• Tests in tests/e2e/{auth,dashboard,invoices,payments,responsive}/
• Page objects in tests/page-objects/
• Mocks all backend API calls for speed and reliability
• See reports-app/frontend/tests/README.md for details

Telegram Bot Tests

cd reports-app/telegram-bot/

# Run all tests
pytest tests/ -v

# Run specific test suites
pytest tests/test_auth.py -v       # Authentication flow tests
pytest tests/test_session_company.py -v # Session management tests

# Run with coverage
pytest tests/ --cov=app --cov-report=html

Telegram Bot Test Coverage:

• Authentication flow tests (link/unlink, JWT management)
• Session management tests (active company persistence)
• Manual testing checklist: tests/MANUAL_TESTING_CHECKLIST.md

🔑 Authentication Flow

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

Key Files:

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

🔌 API Endpoints

All endpoints prefixed with /api:

Authentication

• POST /api/auth/login - Login with username/password

Companies

• GET /api/companies - Get user's accessible companies

Dashboard

• GET /api/dashboard/{company_id} - Dashboard statistics

Invoices

• GET /api/invoices/{company_id} - List invoices with filters
• GET /api/invoices/{company_id}/summary - Invoice summary stats

Treasury

• GET /api/treasury/{company_id} - Treasury/payment data

Telegram Bot

• POST /api/telegram/auth/generate-code - Generate 8-char linking code (requires JWT)
• POST /api/telegram/auth/verify-user - Verify Oracle user_id (public)
• POST /api/telegram/auth/refresh-token - Refresh JWT token (public)
• POST /api/telegram/export - Export reports for Telegram (requires JWT)
• GET /api/telegram/health - Health check (public)

Backend Routers: reports-app/backend/app/routers/{companies,dashboard,invoices,treasury,telegram}.py

🎨 Frontend Stack

• Framework: Vue.js 3 (Composition API)
• UI Library: PrimeVue (rich component library)
• State Management: Pinia stores in src/stores/
• Routing: Vue Router in src/router/
• Build Tool: Vite
• Charts: Chart.js via vue-chartjs
• HTTP: Axios
• Testing: Playwright (E2E)

Key Frontend Components:

• src/views/LoginView.vue - Login page
• src/views/DashboardView.vue - Main dashboard
• src/views/InvoicesView.vue - Invoice management
• src/components/dashboard/cards/ - Dashboard metric cards
• src/components/layout/ - Layout components

🤖 Telegram Bot Frontend

The Telegram Bot provides an alternative command-based interface to ROA2WEB for Telegram users.

Architecture

• Bot Framework: python-telegram-bot (v20.7+)
• Database: Standalone SQLite (auth codes, sessions, active company)
• Backend Communication: HTTP API client (httpx)
• Internal API: FastAPI (port 8002) for backend callbacks

Development Commands

cd reports-app/telegram-bot/

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with TELEGRAM_BOT_TOKEN

# Run bot
python -m app.main

# Health check
curl http://localhost:8002/internal/health

Authentication Flow (Telegram)

1. User logs into ROA2WEB web app
2. User requests Telegram linking → Backend generates 8-char code
3. Backend saves code to telegram-bot via POST /internal/save-code (port 8002)
4. User sends code to Telegram bot: /start ABC123XY
5. Bot verifies code, creates user in SQLite, receives JWT token
6. User can now use commands to query data

Bot Commands

• /start [code] - Welcome message or link account with code
• /help - Usage guide and available commands
• /companies - View accessible companies
• /selectcompany [name] - Select or search for active company
• /dashboard - View financial dashboard for active company
• /sold - View balance (alias for /dashboard)
• /facturi [filter] - View invoices (optional filters: neplatite, platite)
• /trezorerie - View treasury/payment data
• /clear - Clear active company selection
• /unlink - Unlink Telegram from Oracle account

Database (SQLite)

Standalone database in data/telegram_bot.db:

• telegram_users: Telegram-Oracle account linking
• telegram_auth_codes: 8-char codes (15 min expiry)
• telegram_sessions: Active company selection

Automatic cleanup runs hourly to remove expired data.

Testing

# Unit and integration tests
pytest tests/ -v

# Coverage report
pytest tests/ --cov=app --cov-report=html

Key Files

• app/main.py - Bot entry point and Telegram application setup
• app/bot/handlers.py - Telegram command handlers
• app/bot/helpers.py - Helper functions for commands
• app/bot/formatters.py - Response formatting utilities
• app/agent/session.py - Session management (active company)
• app/auth/linking.py - Account linking logic
• app/db/operations.py - SQLite CRUD operations
• app/api/client.py - Backend API client
• app/internal_api.py - Internal FastAPI for backend callbacks

See reports-app/telegram-bot/README.md for complete documentation.

🐳 Docker & Production

Docker Compose (Legacy Flask App)

The root docker-compose.yaml is for the old Flask application - NOT for the current FastAPI/Vue.js app.

Production Deployment Options

ROA2WEB supports two production deployment architectures:

🐧 Linux Production (Docker)

# Setup production environment
./setup_production.sh

# Deployment scripts
./scripts/deploy.sh           # Deploy application
./scripts/backup.sh           # Backup data
./scripts/rollback.sh         # Rollback deployment
./scripts/health-check.sh     # Health monitoring

See DEPLOYMENT_GUIDE.md for full Linux/Docker deployment instructions.

🪟 Windows Server Production (IIS)

Windows Server deployment uses IIS and Windows Services without Docker:

Build deployment package (on WSL/Linux development machine):

cd deployment/windows/scripts
./Build-Frontend.ps1

# Output: ./deploy-package/
# Transfer this to Windows Server

Deploy on Windows Server (PowerShell as Administrator):

# Initial installation
cd C:\path\to\deploy-package\scripts
.\Install-ROA2WEB.ps1

# Configure application
notepad C:\inetpub\wwwroot\roa2web\backend\.env

# Deploy application files
.\Deploy-ROA2WEB.ps1 -SourcePath "C:\path\to\deploy-package"

# Management
.\Start-ROA2WEB.ps1
.\Stop-ROA2WEB.ps1
.\Restart-ROA2WEB.ps1

# Check status
Get-Service ROA2WEB-Backend
Get-Website ROA2WEB

Windows Deployment Architecture:

• IIS Web Server: Serves frontend static files (port 80/443)
• Windows Service: FastAPI backend via NSSM (port 8000)
• Windows Service: Telegram Bot via NSSM (internal API port 8002)
• Direct Oracle Connection: No SSH tunnel required
• URL Rewrite Module: Reverse proxy for /api/* routes

Telegram Bot Integration:

• Backend must have TELEGRAM_BOT_INTERNAL_API=http://localhost:8002 in .env
• Telegram Bot service must be running before generating linking codes
• Troubleshooting: See deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md

See deployment/windows/docs/WINDOWS_DEPLOYMENT.md for complete Windows deployment guide.

📝 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 with app.include_router(your_router, prefix="/api/your_prefix")

Adding Shared Functionality

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

Working with Oracle Stored Procedures

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()

Frontend API Integration

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

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

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

🔒 Security

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

🐛 Troubleshooting

SSH Tunnel Issues

# Check tunnel status
./ssh_tunnel.sh status

# View tunnel logs
ps aux | grep ssh | grep 1526

# Test Oracle connectivity through tunnel
timeout 5 bash -c "cat < /dev/null > /dev/tcp/127.0.0.1/1526"

Backend Not Starting

• Ensure SSH tunnel is running
• Check .env file exists with correct credentials
• Verify virtual environment is activated
• Check port 8001 is not already in use: lsof -ti:8001

Frontend Build Issues

• Clear node_modules: rm -rf node_modules && npm install
• Check Node.js version: node -v (requires 16+)
• Vite may auto-assign ports 3000-3005 if 3000 is busy

Database Connection Errors

• Verify SSH tunnel: ./ssh_tunnel.sh status
• Check Oracle listener is running on remote server
• Verify credentials in .env file
• Test connection: http://localhost:8001/health

📚 Additional Documentation

General Documentation

• README.md - Project overview
• DEVELOPMENT_BLUEPRINT.md - Detailed development plan
• ARCHITECTURE_SCHEMA.md - Architecture diagrams and schemas
• MICROSERVICES_GUIDE.md - Microservices architecture details

Deployment Documentation

• 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 deployment guide

Component Documentation

• reports-app/backend/README.md - Backend specifics
• reports-app/frontend/README.md - Frontend guide
• reports-app/frontend/tests/README.md - Testing guide
• reports-app/telegram-bot/README.md - Telegram bot complete guide
• reports-app/telegram-bot/TELEGRAM_COMMANDS.md - Command reference

🔧 Tech Stack Summary

Backend:

• FastAPI (async Python web framework)
• python-oracledb (Oracle database driver)
• JWT (PyJWT for authentication)
• Pydantic (data validation)
• pytest (testing)

Frontend:

• Vue.js 3 (Composition API)
• PrimeVue (UI components)
• Pinia (state management)
• Vite (build tool)
• Playwright (E2E testing)
• Axios (HTTP client)
• Chart.js (data visualization)

Telegram Bot Frontend:

• python-telegram-bot (Telegram API wrapper)
• SQLite + aiosqlite (standalone database)
• httpx (async HTTP client for backend)
• FastAPI + uvicorn (internal API)
• pytest + pytest-asyncio (testing)

Infrastructure:

• Oracle Database (enterprise data)
• SQLite (Telegram bot standalone data)
• SSH Tunnel (secure database access - Linux/development)
• Nginx (reverse proxy - Linux production)
• Docker Compose (orchestration - Linux production)
• Windows Server + IIS (Windows production deployment)
• NSSM (Windows service manager for backend)