ROA2WEB - Modern ERP Reports Application

FastAPI Backend + Vue.js 3 Frontend + Telegram Bot

Modern microservices-based ERP reporting application for managing invoices, payments, and financial data with Oracle database integration.

---

Project Overview

ROA2WEB is a comprehensive financial reporting platform built with modern technologies:

• Backend: FastAPI (Python) - High-performance async API
• Frontend: Vue.js 3 + PrimeVue - Rich, responsive web interface
• Telegram Bot: Alternative command-based interface
• Database: Oracle Database with connection pooling
• Architecture: Microservices with shared components

---

Quick Start

Prerequisites

• Python 3.11+
• Node.js 16+
• Oracle Database access
• SSH access to Oracle server (for development)

Development Setup

# Clone repository
git clone <repository-url>
cd roa2web

# Start all services (SSH tunnel + Backend + Frontend)
cd roa2web
./start-dev.sh

# Or start services individually:

# 1. Start SSH tunnel for Oracle DB
./ssh_tunnel.sh start

# 2. Start FastAPI backend (port 8001)
cd reports-app/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

# 3. Start Vue.js frontend (port 3000-3005)
cd reports-app/frontend
npm install
npm run dev

# 4. Start Telegram Bot (optional, port 8002)
cd reports-app/telegram-bot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m app.main

Access the Application

• Frontend: http://localhost:3000 (or 3001-3005 if 3000 is busy)
• Backend API Docs: http://localhost:8001/docs (Swagger UI)
• Backend ReDoc: http://localhost:8001/redoc
• Health Check: http://localhost:8001/health

---

Architecture

Directory Structure

├── shared/                    # Shared components
│   ├── database/             # Oracle connection pool (singleton)
│   ├── auth/                 # JWT authentication & middleware
│   └── utils/                # Common utilities
│
├── reports-app/              # Main reports application
│   ├── backend/              # FastAPI backend (port 8001)
│   ├── frontend/             # Vue.js 3 frontend (port 3000-3005)
│   └── telegram-bot/         # Telegram bot (port 8002)
│
├── nginx/                    # Nginx reverse proxy config
├── ssh-tunnel/              # SSH tunnel for Oracle DB
├── deployment/              # Deployment scripts (Linux & Windows)
└── scripts/                 # Utility scripts

Key Features

• Shared Database Pool: Singleton Oracle connection pool shared across microservices
• JWT Authentication: Secure token-based auth with middleware
• Microservices: Independent services with clear separation of concerns
• Oracle Integration: Direct Oracle stored procedure calls
• Responsive Design: Mobile-friendly Vue.js interface
• Telegram Integration: Alternative bot-based interface

---

Core Technologies

Backend

• FastAPI: Modern, high-performance Python web framework
• python-oracledb: Oracle database driver with connection pooling
• JWT (PyJWT): Token-based authentication
• Pydantic: Data validation and settings management
• pytest: Comprehensive testing

Frontend

• Vue.js 3: Progressive JavaScript framework (Composition API)
• PrimeVue: Rich UI component library
• Pinia: State management
• Vue Router: Client-side routing
• Vite: Fast build tool
• Axios: HTTP client
• Chart.js: Data visualization
• Playwright: E2E testing

Telegram Bot

• python-telegram-bot: Telegram Bot API wrapper
• SQLite + aiosqlite: Standalone database for bot data
• httpx: Async HTTP client for backend communication
• FastAPI: Internal API for backend callbacks

Infrastructure

• Oracle Database: Enterprise data storage
• SSH Tunnel: Secure database access (development)
• Nginx: Reverse proxy and load balancer (production)
• Docker: Containerization (production)

---

Development Commands

Backend (FastAPI)

cd reports-app/backend

# Development server with auto-reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

# Run tests
pytest -v

# API documentation
# Swagger UI: http://localhost:8001/docs
# ReDoc: http://localhost:8001/redoc

Frontend (Vue.js)

cd reports-app/frontend

# Development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

# E2E tests (Playwright)
npm run test:e2e
npm run test:e2e:ui    # Interactive UI mode
npm run test:e2e:debug # Debug mode

Telegram Bot

cd reports-app/telegram-bot

# Run bot
python -m app.main

# Run tests
pytest tests/ -v

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

SSH Tunnel Management

cd roa2web

# Start tunnel (localhost:1526 -> remote Oracle:1521)
./ssh_tunnel.sh start

# Check status
./ssh_tunnel.sh status

# Stop tunnel
./ssh_tunnel.sh stop

# Restart tunnel
./ssh_tunnel.sh restart

---

Testing

Backend Tests

cd shared
python -m pytest -v

Frontend E2E Tests

cd reports-app/frontend
npm run test:e2e        # Headless mode
npm run test:e2e:headed # With browser UI
npm run test:e2e:ui     # Interactive mode

Telegram Bot Tests

cd reports-app/telegram-bot
pytest tests/ -v
pytest tests/ --cov=app --cov-report=html

---

Production Deployment

Linux/Docker Deployment

cd roa2web

# Setup production environment
./setup_production.sh

# Deploy application
./scripts/deploy.sh

# Health check
./scripts/health-check.sh

See DEPLOYMENT_GUIDE.md for complete deployment instructions.

Windows Server Deployment

ROA2WEB supports deployment on Windows Server with IIS:

# On Windows Server (PowerShell as Administrator)
cd C:\path\to\roa2web\deployment\windows\scripts

# Install
.\Install-ROA2WEB.ps1

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

# Manage services
.\Start-ROA2WEB.ps1
.\Stop-ROA2WEB.ps1
.\Restart-ROA2WEB.ps1

See deployment/windows/docs/WINDOWS_DEPLOYMENT.md for details.

---

API Endpoints

All endpoints prefixed with /api:

Authentication

• POST /api/auth/login - Login with Oracle credentials

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

Treasury

• GET /api/treasury/{company_id} - Payment data

Telegram Bot

• POST /api/telegram/auth/generate-code - Generate linking code
• POST /api/telegram/auth/verify-user - Verify Oracle user
• POST /api/telegram/auth/refresh-token - Refresh JWT token
• POST /api/telegram/export - Export reports

---

Environment Configuration

Copy .env.example to .env in each microservice and configure:

Backend (reports-app/backend/.env)

# Oracle Database (through SSH tunnel)
ORACLE_USER=your_username
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 (reports-app/telegram-bot/.env)

# Telegram Bot Token
TELEGRAM_BOT_TOKEN=your_bot_token

# Backend API
BACKEND_API_URL=http://localhost:8001

---

Documentation

General

• CLAUDE.md - Development guide for Claude Code
• DEVELOPMENT_BLUEPRINT.md - Detailed development plan
• TEAM_IMPLEMENTATION_GUIDE.md - Team implementation guide
• ARCHITECTURE_SCHEMA.md - Architecture diagrams
• MICROSERVICES_GUIDE.md - Microservices details

Component-Specific

• README.md - Main application README
• reports-app/backend/README.md - Backend specifics
• reports-app/frontend/README.md - Frontend guide
• reports-app/frontend/tests/README.md - Frontend testing
• reports-app/telegram-bot/README.md - Telegram bot guide
• reports-app/telegram-bot/TELEGRAM_COMMANDS.md - Bot commands

Deployment

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

---

Contributing

1. Create feature branch from main
2. Make changes following project structure
3. Write tests for new features
4. Run all tests before committing
5. Create pull request with clear description

---

License

[Your License Here]

---

Support

For issues and questions:

• Check documentation in `` subdirectories
• Review CLAUDE.md for development guidelines
• See component-specific READMEs for detailed information

---

Branch: v2-roa2web-fastapi Working Directory: `` - All development happens here