roa2web-service-auto/README.md

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 with one command
./start-dev.sh

This starts SSH tunnel, backend (port 8001), and frontend (port 3000-3005).

For individual service setup or troubleshooting: See "Development & Testing" section below or component-specific READMEs.

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
• 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-dev.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: reports-app/backend/README.md
• Frontend: reports-app/frontend/README.md & reports-app/frontend/tests/README.md
• Telegram Bot: reports-app/telegram-bot/README.md

Key Commands:

./ssh_tunnel.sh start                              # Start Oracle DB tunnel
cd reports-app/backend && uvicorn app.main:app --reload  # Backend (port 8001)
cd reports-app/frontend && npm run dev             # Frontend (port 3000-3005)
cd reports-app/telegram-bot && python -m app.main  # Telegram Bot (port 8002)

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

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

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