romfast/roa2web-service-auto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Migrate to ultrathin monolith architecture

Browse Source 
Consolidate 3 separate applications (reports-app, data-entry-app, telegram-bot) into a unified
architecture with single backend and frontend:

Backend Changes:
- Unified FastAPI backend at backend/ with modular structure
- Modules: reports, data_entry, telegram in backend/modules/
- Centralized config.py and main.py with all routers registered
- Single worker mode (--workers 1) for Telegram bot compatibility
- Shared Oracle connection pool and JWT authentication
- Unified requirements.txt and environment configuration

Frontend Changes:
- Single Vue.js SPA with module-based routing
- Unified frontend at src/ with modules in src/modules/{reports,data-entry}/
- Shared components and stores in src/shared/
- Error boundaries for module isolation
- Dual API proxy in Vite for module communication

Infrastructure:
- New unified startup scripts: start-prod.sh, start-test.sh, start-backend.sh
- Environment templates: .env.dev.example, .env.test.example, .env.prod.example
- Updated deployment scripts for Windows IIS
- Simplified SSH tunnel management

Documentation:
- Comprehensive CLAUDE.md with architecture overview
- Module-specific docs in docs/{data-entry,telegram}/
- Architecture decision records in docs/ARCHITECTURE-DECISIONS.md
- Deployment guides consolidated in deployment/windows/docs/

This migration reduces complexity, improves maintainability, and enables easier
deployment while maintaining all existing functionality.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Marius Mutu
2025-12-29 23:48:14 +02:00
parent 2a101f1ef5
commit c5e051ad80
378 changed files with 7566 additions and 73730 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
CLAUDE.md
View File

@@ -4,9 +4,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## 🚀 Project Overview
**ROA2WEB** - Modern ERP Application with two main modules:
1. **Reports App** (`reports-app/`) - Read-only reports from Oracle (raportări)
2. **Data Entry App** (`data-entry-app/`) - Data input with approval workflow (introduceri date)
**ROA2WEB** - Modern ERP Application with ultrathin monolith architecture:
1. **Reports Module** (`backend/modules/reports/`) - Read-only reports from Oracle (raportări)
2. **Data Entry Module** (`backend/modules/data_entry/`) - Data input with approval workflow (introduceri date)
3. **Telegram Bot Module** (`backend/modules/telegram/`) - Telegram bot integration
**Main Branch**: `main` (use for PRs)
**Working Directory**: Repository root
@@ -15,57 +16,74 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
---
## 📁 Application-Specific Instructions
## 📁 Module-Specific Instructions
> **IMPORTANT**: When working on a specific application, ALWAYS read its dedicated CLAUDE.md first!
> **IMPORTANT**: When working on a specific module, read its documentation first!
| Application | CLAUDE.md Location | Description |
|-------------|-------------------|-------------|
| **Data Entry** | `data-entry-app/CLAUDE.md` | Bonuri fiscale, chitanțe, workflow aprobare |
| Module | Documentation Location | Description |
|--------|----------------------|-------------|
| **Data Entry** | `docs/data-entry/DATA-ENTRY-MODULE.md` | Bonuri fiscale, chitanțe, workflow aprobare |
| **Reports** | This file (below) | Rapoarte Oracle read-only |
| **Telegram Bot** | `reports-app/telegram-bot/README.md` | Bot Telegram |
| **Telegram Bot** | `docs/telegram/README.md` | Bot Telegram |
### When to Use Which Instructions
**Working on `data-entry-app/`**:
→ **FIRST read `data-entry-app/CLAUDE.md`** for:
**Working on Data Entry** (`backend/modules/data_entry/` or `src/modules/data-entry/`):
→ **FIRST read `docs/data-entry/DATA-ENTRY-MODULE.md`** for:
- SQLModel + Alembic patterns (NOT Oracle)
- SQLite database (NOT Oracle pool)
- Workflow states (DRAFT → PENDING → APPROVED)
- Receipt/Attachment/AccountingEntry models
- Expense types and auto-generation logic
- Oracle nomenclatures integration
**Working on `reports-app/` or `shared/`**:
**Working on Reports Module** (`backend/modules/reports/` or `src/modules/reports/`):
→ Use instructions from this file (below)
**Working on shared components** (`shared/auth/`, `shared/database/`, `shared/frontend/`):
→ These are used by BOTH apps - be careful with changes!
→ These are used by ALL modules - be careful with changes!
→ `shared/frontend/` contains: LoginView.vue, auth store factory, login styles
---
## 🏗️ Architecture
### Microservices Structure
> **Important Architecture Decisions:** See `docs/ARCHITECTURE-DECISIONS.md` for critical decisions about:
> - Why single worker (`--workers 1`) is required for Telegram bot
> - Ultrathin monolith vs microservices rationale
> - IIS sub-application deployment strategy
> - Performance characteristics and scaling considerations
### Ultrathin Monolith Structure
```
.
├── shared/ # Shared components (DB pool, auth, frontend)
│ ├── database/ # Oracle pool (used by both apps)
│ ├── auth/ # JWT auth (used by both apps)
│ └── frontend/ # Shared Vue components, stores, styles
│ ├── components/ # LoginView.vue
│ ├── stores/ # auth.js (Pinia store factory)
│ └── styles/ # login.css
├── backend/ # Unified FastAPI backend (port 8000/8001)
│ ├── modules/ # Business logic modules
│ │ ├── reports/ # Reports module (Oracle read-only)
│ │ ├── data_entry/ # Data entry module (SQLite + workflow)
│ │ ├── telegram/ # Telegram bot module
│ │ └── data/ # Shared data (telegram_bot.db)
│ ├── config.py # Centralized configuration
│ └── main.py # FastAPI app entry point
│
├── reports-app/ # READ-ONLY reports from Oracle
│ ├── backend/ # FastAPI API (port 8001)
│ ├── frontend/ # Vue.js 3 UI (port 3000-3005)
│ └── telegram-bot/ # Telegram bot (port 8002 internal)
├── src/ # Unified Vue.js 3 frontend
│ ├── modules/ # Feature modules
│ │ ├── reports/ # Reports frontend
│ │ └── data-entry/ # Data entry frontend
│ ├── shared/ # Shared frontend components
│ │ ├── components/ # Reusable Vue components
│ │ └── stores/ # Pinia stores
│ ├── assets/ # Global CSS, images
│ ├── router/ # Vue Router
│ └── App.vue # Root component
│
├── data-entry-app/ # DATA INPUT with approval workflow
│ ├── backend/ # FastAPI API (port 8003) - SQLite + SQLModel
│ ├── frontend/ # Vue.js 3 UI (port 3010)
│ └── CLAUDE.md # ⚠️ READ THIS for data-entry work!
├── shared/ # Shared backend components
│ ├── database/ # Oracle pool
│ ├── auth/ # JWT auth & middleware
│ └── frontend/ # Shared frontend assets
│ ├── components/ # LoginView.vue
│ ├── stores/ # Auth store factory
│ └── styles/ # Login CSS
│
├── docs/ # Architecture & style guides
├── deployment/ # Production deployment scripts
@@ -74,39 +92,49 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
### Starting Services
**Quick Start** (All services with parallel backend startup):
**Quick Start** (Unified backend + frontend):
```bash
./start-dev.sh # Dev: Backend :8001, :8003, Bot :8002, Frontend :3000 (~11s)
./start-test.sh # Test: Same ports (~33s - Oracle pool init takes longer)
./start-prod.sh # Prod env: Backend :8001, Frontend :3000
./start-test.sh # Test env: Backend :8001, Frontend :3000
```
**Individual Service Control** (for quick development iterations):
**Individual Service Control**:
```bash
./frontend.sh restart # Restart frontend only (~7s - fastest!)
./backend-reports.sh start # Start Reports backend :8001
./backend-data-entry.sh stop # Stop Data Entry backend :8003
./bot.sh status # Check Telegram bot :8002 status
./status.sh # Show all services status + health checks
./start-frontend.sh restart # Restart frontend only (~7s - fastest!)
./start-backend.sh # Start unified backend :8000 or :8001
./status.sh # Show services status + health checks
```
**Infrastructure**:
```bash
./ssh_tunnel.sh start # Oracle DB tunnel (production: 10.0.20.36)
./ssh-tunnel-test.sh start # Oracle TEST tunnel (LXC: 10.0.20.121)
./ssh-tunnel-prod.sh start # Oracle DB tunnel (production: 10.0.20.36)
./ssh-tunnel-test.sh start # Oracle TEST tunnel (LXC: 10.0.20.121)
```
**Benefits**:
- **87% faster frontend restart**: 7s vs 53s full restart
- **38% faster full startup**: 33s vs 53s (test) via parallel backend init
- **Granular control**: Restart individual services without affecting others
- **Single backend process**: All modules in one FastAPI app
- **Faster startup**: No multi-service coordination overhead
- **Easier debugging**: Single process to monitor
- **Shared resources**: Connection pools, cache, and middleware
### Key Architectural Decisions
**Core Architecture:**
- **Ultrathin Monolith**: Single backend process with modular structure (`backend/modules/`)
- **Single Worker Mode**: `--workers 1` (required for Telegram bot - see ADR-002 in `docs/ARCHITECTURE-DECISIONS.md`)
- **Shared Database Pool**: Singleton `OraclePool` in `shared/database/oracle_pool.py` (python-oracledb with connection pooling)
- **Centralized Auth**: JWT-based auth in `shared/auth/` with middleware auto-injecting `request.state.user`
- **Two-Tier Cache System**: Hybrid L1 (Memory) + L2 (SQLite) cache in `backend/app/cache/` - **MANDATORY for all new endpoints**
**Module-Specific:**
- **Module-Based Cache**: Each module can have its own cache strategy (Reports uses L1+L2 hybrid cache)
- **Telegram Bot**: Integrated module with SQLite database (`backend/modules/data/telegram_bot.db`)
- **FastAPI Structure**: Modules in `backend/modules/*/`, each with services, routers, models/schemas
**Infrastructure:**
- **SSH Tunnel**: Required for Oracle DB connections (development/Linux) - see Database Setup
- **FastAPI Structure**: Services in `backend/app/services/` with `@cached` decorator, routers in `backend/app/routers/`, models in `backend/app/models/` or `schemas/`
- **Telegram Bot**: Standalone SQLite database for bot data, communicates with backend via HTTP API
- **IIS Sub-Application**: Deployed at `/roa2web` path, not root (production)
> **For detailed rationale and trade-offs**, see `docs/ARCHITECTURE-DECISIONS.md`
---
@@ -117,14 +145,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
### SSH Tunnel (Development/Linux)
```bash
./ssh_tunnel.sh start # localhost:1526 → remote:1521
./ssh_tunnel.sh status # Check tunnel
./ssh_tunnel.sh stop # Stop tunnel
./ssh-tunnel-prod.sh start # localhost:1526 → remote:1521
./ssh-tunnel-prod.sh status # Check tunnel
./ssh-tunnel-prod.sh stop # Stop tunnel
```
**IMPORTANT**: Always ensure SSH tunnel is running before starting backend services.
### Environment Variables (`reports-app/backend/.env`)
### Environment Variables (`backend/.env`)
```bash
# Oracle Database (through SSH tunnel)
ORACLE_USER=CONTAFIN_ORACLE
@@ -138,11 +166,14 @@ JWT_SECRET_KEY=your_secret_key
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=30
# Telegram Bot Integration
TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
# Module Configuration
MODULE_REPORTS_ENABLED=true
MODULE_DATA_ENTRY_ENABLED=true
MODULE_TELEGRAM_ENABLED=true
```
**Windows Production**: Direct Oracle connection, no SSH tunnel required. Ensure `TELEGRAM_BOT_INTERNAL_API` is set for auth code management.
**Windows Production**: Direct Oracle connection, no SSH tunnel required.
**Environment Files**: Multiple .env files available (.env.dev, .env.test, .env.prod) - see `backend/ENV-SETUP.md` for details.
---
@@ -156,7 +187,7 @@ TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
**Key Files**:
- `shared/auth/middleware.py` - FastAPI middleware with rate limiting (5 req/5 min)
- `shared/auth/jwt_handler.py` - Token creation/validation
- `reports-app/backend/app/main.py` - Auth router inline definition
- `backend/main.py` - Main FastAPI app with auth router registration
---
@@ -165,10 +196,10 @@ TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
### Adding a New API Endpoint
**IMPORTANT**: Always use the cache system for database queries to improve performance.
1. Create **service** in `reports-app/backend/app/services/your_service.py` (NOT in router!)
2. Define Pydantic schemas in `app/schemas/` or `app/models/`
1. Create **service** in `backend/modules/reports/services/your_service.py` (NOT in router!)
2. Define Pydantic schemas in `modules/*/schemas/` or `modules/*/models/`
3. **Add caching** using `@cached` decorator in service methods
4. Create router in `reports-app/backend/app/routers/your_router.py` (calls service)
4. Create router in `backend/modules/reports/routers/your_router.py` (calls service)
5. Register router in `app/main.py`: `app.include_router(your_router, prefix="/api/your_prefix")`
**Service Example with Caching** (RECOMMENDED):
@@ -278,7 +309,7 @@ ttl_your_data: int = int(os.getenv('CACHE_TTL_YOUR_DATA', '600')) # 10 min defa
### Adding a New Telegram Bot Command
**IMPORTANT**: Follow established command patterns and formatting.
**Before coding**: Read **`reports-app/telegram-bot/TELEGRAM_COMMANDS.md`** for command patterns → See "Documentation Index" for complete guides.
**Before coding**: Read **`docs/telegram/TELEGRAM_BUTTON_INTERFACE_PLAN.md`** for command patterns → See "Documentation Index" for complete guides.
**Standard Pattern** (add handler in `app/bot/handlers.py`):
```python
@@ -338,14 +369,12 @@ const response = await api.get('/endpoint');
→ **`README.md`** - Project overview, setup, development commands, testing, deployment
### Data Entry App (Bonuri Fiscale)
- **`data-entry-app/CLAUDE.md`** - ⚠️ **READ FIRST** when working on data-entry
- `data-entry-app/README.md` - Quick start guide
- **`docs/data-entry/CLAUDE.md`** - ⚠️ **READ FIRST** when working on data-entry
- `docs/data-entry/README.md` - Quick start guide
- `docs/data-entry/REQUIREMENTS.md` - Functional requirements
- `docs/data-entry/ARCHITECTURE.md` - Technical architecture (SQLModel, workflow)
### Architecture & Planning
- **`docs/ARCHITECTURE_SCHEMA.md`** - Architecture diagrams, cache system, and schemas
- `docs/MICROSERVICES_GUIDE.md` - Microservices architecture details
- `DEVELOPMENT_BLUEPRINT.md` - Detailed development plan
### Frontend Development
@@ -355,20 +384,19 @@ const response = await api.get('/endpoint');
- `docs/STYLING_GUIDELINES.md` - CSS best practices and conventions
- `docs/COMPONENT_STYLING.md` - Component-specific styling guide
- `docs/FORM_TEMPLATE.md` - Standardized form template
- `reports-app/frontend/README.md` - Frontend architecture and setup
- `reports-app/frontend/tests/README.md` - Playwright E2E testing guide
- `Frontend module documentation in src/modules/` - Frontend architecture and setup
- `Playwright E2E testing (see tests/ directory)` - Playwright E2E testing guide
### Backend Development
- `reports-app/backend/README.md` - Backend architecture and API details
- `Backend module documentation in backend/modules/` - Backend architecture and API details
- API endpoints documented in `README.md` (Authentication, Companies, Dashboard, Invoices, Treasury, Telegram)
### Telegram Bot Development
- **`reports-app/telegram-bot/README.md`** - Complete bot architecture and development guide (START HERE)
- **`reports-app/telegram-bot/TELEGRAM_COMMANDS.md`** - Command reference and patterns
- **`docs/telegram/README.md`** - Complete bot architecture and development guide (START HERE)
- **`docs/telegram/TELEGRAM_BUTTON_INTERFACE_PLAN.md`** - Command reference and patterns
- `tests/MANUAL_TESTING_CHECKLIST.md` - Manual testing procedures
### Deployment
- **`DEPLOYMENT_GUIDE.md`** - Production deployment (Linux/Docker & Windows/IIS)
- `deployment/windows/README.md` - Windows deployment quick start
- `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` - Complete Windows guide
- `deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md` - Bot troubleshooting