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-prod.sh

This starts SSH tunnel, unified backend (port 8001), 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
• Microservices: Independent services 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-prod.sh 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 (FAST with parallel backend startup - ~11s dev, ~33s test)
./start-prod.sh                    # Start all (SSH tunnel + Backends + Bot + Frontend)
./start-test.sh                   # Start all (TEST environment)

# Individual Service Control (NEW - for quick restarts!)
./start-frontend.sh start|stop|restart|status        # Frontend only (~7s restart!)
./backend-reports.sh start|stop|status         # Reports backend only
./backend-data-entry.sh start|stop|status      # Data Entry backend only
./bot.sh start|stop|status                     # Telegram bot only

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

# Infrastructure Only
./ssh-tunnel-prod.sh start|stop|status             # Oracle DB tunnel (production)
./ssh-tunnel-test.sh start|stop|status        # Oracle TEST tunnel

💡 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
• Backend-uri pornesc în paralel în start-prod.sh și start-test.sh pentru pornire mai rapidă

📖 Usage Flow

Individual scripts (start-frontend.sh, start-backend.sh, backend-*.sh, bot.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-prod.sh, start-test.sh) set the environment:

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

Recommended workflow:

# Morning: Start full stack with environment selection
./start-prod.sh                    # 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-prod.sh

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

Common scenarios:

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

# Scenario 2: Debugging a single backend
./start-prod.sh stop               # Stop all
./ssh-tunnel-prod.sh start             # Infrastructure only
./backend-reports.sh start        # Just the backend you need
./start-frontend.sh start               # Just the frontend

# Scenario 3: Testing mode
./start-test.sh                   # 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-test.sh 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

---

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_SCHEMA.md - Architecture diagrams, cache system, and schemas
• docs/MICROSERVICES_GUIDE.md - Microservices architecture details
• DEVELOPMENT_BLUEPRINT.md - Detailed development plan

Component-Specific

• README.md - Main application README
• backend/ modules and CLAUDE.md - Backend specifics
• src/ and docs/MONOLITH_ARCHITECTURE.md - Frontend guide
• E2E testing guide in docs/ - Frontend testing
• backend/modules/telegram/README.md - Telegram bot guide
• backend/modules/telegram/TELEGRAM_COMMANDS.md - Bot commands

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/STYLING_GUIDELINES.md - CSS best practices and conventions
• docs/COMPONENT_STYLING.md - Component-specific styling guide
• docs/FORM_TEMPLATE.md - Standardized form template and patterns

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