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

```bash
# 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**:
```bash
# 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:**

```bash
# 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:**

```bash
# 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
```bash
./setup_production.sh              # Initial setup
./scripts/deploy.sh                # Deploy application
./scripts/health-check.sh          # Health monitoring
```

### 🪟 Windows/IIS Deployment

**Modern Unified Workflow** (recommended):
```powershell
# 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**:
```powershell
# 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:**
```bash
# 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:**
```powershell
# 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`:
```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:
  ```powershell
  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`)
```bash
# 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`)
```bash
# 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