roa2web-service-auto/README.md

ROA2WEB - Modern ERP Application

FastAPI Backend + Vue.js 3 Frontend + Telegram Bot

Modern ultrathin monolith ERP application for managing reports, data entry, and financial data with Oracle database integration.

---

Project Overview

ROA2WEB is a comprehensive financial platform built with modern technologies:

• Backend: FastAPI (Python) - Unified async API with modular architecture
• Frontend: Vue.js 3 + PrimeVue - Single-page application with lazy-loaded modules
• Telegram Bot: Alternative command-based interface (integrated module)
• Database: Oracle Database + SQLite (hybrid approach)
• Architecture: Ultrathin monolith with clear module boundaries

---

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 with one command
./start.sh prod       # Production
./start.sh test       # Test environment

This starts SSH tunnel (if needed), unified backend (port 8000), and frontend (port 3000).

For individual service setup or troubleshooting: See "Development & Testing" section below.

Access the Application

• Frontend: http://localhost:3000
• Backend API Docs: http://localhost:8001/docs (Swagger UI)
• Backend ReDoc: http://localhost:8001/redoc
• Health Check: http://localhost:8001/health

---

Architecture

Ultrathin Monolith Structure

.
├── backend/                   # Unified FastAPI backend (port 8001)
│   ├── modules/              # Business logic modules
│   │   ├── reports/         # Reports module (Oracle read-only)
│   │   ├── data_entry/      # Data entry module (SQLite + workflow)
│   │   └── telegram/        # Telegram bot module
│   ├── config.py            # Centralized configuration
│   └── main.py              # FastAPI app entry point
│
├── src/                      # Unified Vue.js 3 frontend
│   ├── modules/             # Feature modules
│   │   ├── reports/         # Reports frontend
│   │   └── data-entry/      # Data entry frontend
│   ├── shared/              # Shared frontend components
│   ├── assets/              # Global CSS, images
│   └── router/              # Vue Router
│
├── shared/                   # Shared backend components
│   ├── database/            # Oracle connection pool
│   ├── auth/                # JWT authentication
│   └── frontend/            # Shared frontend assets
│
├── docs/                     # Documentation
├── deployment/               # Deployment scripts
└── ssh-tunnel/              # SSH tunnel for Oracle DB

Key Features

• Shared Database Pool: Singleton Oracle connection pool shared across all modules
• Two-Tier Cache System: Hybrid L1 (Memory) + L2 (SQLite) for optimal performance
• JWT Authentication: Secure token-based auth with middleware
• Modular Architecture: Independent modules with clear separation of concerns
• Oracle Integration: Direct Oracle stored procedure calls with caching
• Responsive Design: Mobile-friendly Vue.js interface
• Telegram Integration: Alternative bot-based interface

---

Tech Stack

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

See CLAUDE.md for detailed tech stack information, cache system, and architecture decisions.

---

Development & Testing

Quick Start: Use ./start.sh prod to start all services (SSH tunnel + Backend + Frontend).

For detailed development commands, testing procedures, and troubleshooting: See CLAUDE.md and component-specific READMEs:

• Backend: backend/ modules and CLAUDE.md
• Frontend: src/ and docs/MONOLITH_ARCHITECTURE.md & E2E testing guide in docs/
• Telegram Bot: backend/modules/telegram/README.md

Key Commands:

# Start All Services
./start.sh prod                   # Start PROD (SSH tunnel + Backend + Frontend)
./start.sh test                   # Start TEST (direct Oracle connection)
./start.sh prod stop              # Stop PROD services
./start.sh test stop              # Stop TEST services

# Individual Service Control (for quick restarts)
./start-frontend.sh start|stop|restart|status  # Frontend only (~7s restart!)
./start-backend.sh start|stop|restart|status   # Backend only

# System Monitoring
./status.sh                       # Show all services status + health checks

# Infrastructure Only
./ssh-tunnel.sh start|stop|status              # Oracle DB tunnel (for servers with SSH)

💡 Pro Tips:

• Frontend changes? Use ./start-frontend.sh restart instead of restarting everything (87% faster!)
• Check what's running: ./status.sh shows everything at a glance
• Single unified script: start.sh handles both environments with parameters

📖 Usage Flow

Individual scripts (start-frontend.sh, start-backend.sh) are environment-neutral:

• They DON'T change .env files
• They use whatever .env is already present
• Use them for quick restarts when working on a specific service

Master scripts (start.sh prod, start.sh test) set the environment:

• start.sh prod → uses existing .env files (DEV mode)
• start.sh test → copies .env.test → .env (TEST mode)

Recommended workflow:

# Morning: Start full stack with environment selection
./start.sh prod                    # DEV mode - sets up .env files

# During development: Quick service restarts
./start-frontend.sh restart             # Frontend only (~7s)
./backend-reports.sh restart      # Reports backend only (~30s)
# ⚠️ Individual scripts inherit the environment set by start.sh prod

# End of day: Stop everything
./start.sh prod stop

Common scenarios:

# Scenario 1: Working on frontend only
./start.sh prod                    # Start everything once
./start-frontend.sh restart             # Restart frontend multiple times (fast!)

# Scenario 2: Debugging a single backend
./start.sh prod stop               # Stop all
./ssh-tunnel.sh start              # SSH tunnel (if needed)
./start-backend.sh start           # Just the backend
./start-frontend.sh start          # Just the frontend

# Scenario 3: Testing mode
./start.sh test                    # Starts everything in TEST mode
# All subsequent individual script calls use TEST .env files

# Scenario 4: Check what's running
./status.sh                       # See all services + health checks

Note: For automated testing and validation (/validate command), use start.sh test which starts all services connected to Oracle TEST server (LXC 10.0.20.121) with test credentials.

API Documentation (when backend running):

• Swagger UI: http://localhost:8001/docs
• ReDoc: http://localhost:8001/redoc
• Health Check: http://localhost:8001/health

---

Production Deployment

ROA2WEB supports two deployment architectures:

🐧 Linux/Docker Deployment

./setup_production.sh              # Initial setup
./scripts/deploy.sh                # Deploy application
./scripts/health-check.sh          # Health monitoring

🪟 Windows/IIS Deployment

Modern Unified Workflow (recommended):

# On Development Machine (WSL/Linux)
cd deployment/windows/scripts
.\Publish-And-Deploy.ps1           # Build + Transfer to server (interactive menu)

# On Windows Server (PowerShell as Admin)
cd deployment/windows/scripts
.\ROA2WEB-Console.ps1              # Deploy + Manage services (interactive console)

Alternative - Manual Installation:

# First-time installation
.\Install-ROA2WEB.ps1
.\Install-TelegramBot.ps1

# Automated deployment
.\Check-And-Deploy.ps1

Complete Documentation:

• DEPLOYMENT_GUIDE.md - Comprehensive guide for both platforms
• deployment/windows/README.md - Windows quick start
• deployment/windows/docs/WINDOWS_DEPLOYMENT.md - Complete Windows guide

---

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

---

SSH Tunnel Configuration

ROA2WEB uses SSH tunnels to connect to Oracle servers. Configuration is in backend/ssh-tunnels.json.

Setup (one-time)

Linux:

# Copy SSH key to secrets folder
cp ~/.ssh/your_key backend/secrets/vending.ssh_key
chmod 600 backend/secrets/vending.ssh_key

# Or use password (requires sshpass)
echo "your_password" > backend/secrets/vending.ssh_pass
sudo apt install sshpass

Windows:

# Option 1: SSH Key (recommended)
ssh-keygen -t rsa -b 4096 -f C:\inetpub\wwwroot\roa2web\backend\secrets\vending.ssh_key -N ""
# Then add public key to remote server's ~/.ssh/authorized_keys

# Option 2: Password (requires PuTTY)
choco install putty -y
echo "your_password" > C:\inetpub\wwwroot\roa2web\backend\secrets\vending.ssh_pass

Configuration File

backend/ssh-tunnels.json:

[
  {
    "id": "vending",
    "name": "Vending Master",
    "local_port": 1522,
    "ssh_host": "79.119.86.134",
    "ssh_port": 22122,
    "ssh_user": "romfast",
    "ssh_hostkey": "SHA256:xxxxx",
    "oracle_host": "127.0.0.1",
    "oracle_port": 1521
  }
]

Important:

• local_port must match the port in ORACLE_SERVERS (.env) for this server
• ssh_hostkey is required on Windows (plink batch mode). Get it with:

  plink.exe -ssh user@host -P port "exit"
  # Accept the key, then copy SHA256 fingerprint from output
  

Commands

Platform	Start	Stop	Status
Linux	./ssh-tunnel.sh start	./ssh-tunnel.sh stop	./ssh-tunnel.sh status
Windows	.\scripts\ssh-tunnel.ps1 start	.\scripts\ssh-tunnel.ps1 stop	.\scripts\ssh-tunnel.ps1 status

Auto-Start (Production)

• Linux: start.sh automatically starts tunnels before backend
• Windows Service: start-backend-service.ps1 wrapper starts tunnels before uvicorn
• Auto-Reconnect: Backend monitors tunnels and restarts them if they drop (every 30s check)

---

Environment Configuration

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

Backend (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 (backend/modules/telegram/.env)

# Telegram Bot Token
TELEGRAM_BOT_TOKEN=your_bot_token

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

---

Documentation

Quick Reference

• CLAUDE.md - Development guide for AI/Claude Code (architecture, cache system, common tasks, troubleshooting)
• docs/ARCHITECTURE-DECISIONS.md - Architecture Decision Records (ADRs)
• docs/MONOLITH_ARCHITECTURE.md - Ultrathin monolith architecture details

Module Documentation

• docs/data-entry/DATA-ENTRY-MODULE.md - Data Entry module (SQLModel, workflow, OCR)
• docs/telegram/README.md - Telegram bot integration
• docs/telegram/DEPLOYMENT.md - Telegram single-worker requirement

Frontend Styling & CSS

• docs/ONBOARDING_CSS.md - CSS system onboarding guide (start here!)
• docs/CSS_PATTERNS.md - Comprehensive CSS patterns library
• docs/DESIGN_TOKENS.md - Design tokens reference (colors, spacing, typography)
• docs/MOBILE_PATTERNS.md - Mobile UI patterns and components

Deployment

• docs/DEPLOYMENT.md - Principal deployment guide (start here!)
• deployment/linux/README.md - Deploy from Linux/LXC
• deployment/windows/README.md - Deploy from Windows

Testing

• tests/ocr-validation/README.md - OCR validation tests

---

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