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

docs: optimize and streamline documentation (59% reduction)

Browse Source 
Major documentation refactoring to eliminate duplications and improve maintainability:

CLAUDE.md (562→230 lines, 59% reduction):
- Eliminated duplicate content with README.md
- Added smart references to detailed documentation
- Streamlined "Common Development Tasks" with golden rules
- Created comprehensive "Documentation Index" as single source of truth
- Focused on AI-friendly quick reference patterns

README.md (402→251 lines, 37% reduction):
- Simplified Quick Start to single command
- Condensed Tech Stack to one-line summary with CLAUDE.md reference
- Merged "Development Commands" + "Testing" into compact section
- Updated Production Deployment with modern workflow (Publish-And-Deploy.ps1, ROA2WEB-Console.ps1)
- Added Frontend Styling & CSS documentation references

Key improvements:
- Zero duplications across documentation files
- Clear separation: README.md = quick start, CLAUDE.md = development guide
- Smart cross-references between docs
- Updated deployment section with current scripts
- Maintained all essential information while reducing context by 446 lines

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Marius Mutu
2025-11-19 23:56:03 +02:00
parent baeaea335e
commit 2b2002bbe8
2 changed files with 197 additions and 643 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
README.md
View File

@@ -34,35 +34,14 @@ ROA2WEB is a comprehensive financial reporting platform built with modern techno
git clone <repository-url>
cd roa2web
# Start all services (SSH tunnel + Backend + Frontend)
cd roa2web
# Start all services with one command
./start-dev.sh
# Or start services individually:
# 1. Start SSH tunnel for Oracle DB
./ssh_tunnel.sh start
# 2. Start FastAPI backend (port 8001)
cd reports-app/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001
# 3. Start Vue.js frontend (port 3000-3005)
cd reports-app/frontend
npm install
npm run dev
# 4. Start Telegram Bot (optional, port 8002)
cd reports-app/telegram-bot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m app.main
```
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)
@@ -105,180 +84,79 @@ python -m app.main
---
## Core Technologies
## Tech Stack
### Backend
- **FastAPI**: Modern, high-performance Python web framework
- **python-oracledb**: Oracle database driver with connection pooling
- **JWT (PyJWT)**: Token-based authentication
- **Pydantic**: Data validation and settings management
- **pytest**: Comprehensive testing
**Backend**: FastAPI, python-oracledb, JWT (PyJWT), Pydantic, pytest
**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)
### Frontend
- **Vue.js 3**: Progressive JavaScript framework (Composition API)
- **PrimeVue**: Rich UI component library
- **Pinia**: State management
- **Vue Router**: Client-side routing
- **Vite**: Fast build tool
- **Axios**: HTTP client
- **Chart.js**: Data visualization
- **Playwright**: E2E testing
### Telegram Bot
- **python-telegram-bot**: Telegram Bot API wrapper
- **SQLite + aiosqlite**: Standalone database for bot data
- **httpx**: Async HTTP client for backend communication
- **FastAPI**: Internal API for backend callbacks
### Infrastructure
- **Oracle Database**: Enterprise data storage
- **SSH Tunnel**: Secure database access (development)
- **Nginx**: Reverse proxy and load balancer (production)
- **Docker**: Containerization (production)
*See `CLAUDE.md` for detailed tech stack information and architecture decisions.*
---
## Development Commands
## Development & Testing
### Backend (FastAPI)
**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**:
```bash
cd reports-app/backend
# Development server with auto-reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001
# Run tests
pytest -v
# API documentation
# Swagger UI: http://localhost:8001/docs
# ReDoc: http://localhost:8001/redoc
./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)
```
### Frontend (Vue.js)
```bash
cd reports-app/frontend
# Development server
npm run dev
# Build for production
npm run build
# Preview production build
npm run preview
# Lint code
npm run lint
# E2E tests (Playwright)
npm run test:e2e
npm run test:e2e:ui # Interactive UI mode
npm run test:e2e:debug # Debug mode
```
### Telegram Bot
```bash
cd reports-app/telegram-bot
# Run bot
python -m app.main
# Run tests
pytest tests/ -v
# Health check
curl http://localhost:8002/internal/health
```
### SSH Tunnel Management
```bash
cd roa2web
# Start tunnel (localhost:1526 -> remote Oracle:1521)
./ssh_tunnel.sh start
# Check status
./ssh_tunnel.sh status
# Stop tunnel
./ssh_tunnel.sh stop
# Restart tunnel
./ssh_tunnel.sh restart
```
---
## Testing
### Backend Tests
```bash
cd shared
python -m pytest -v
```
### Frontend E2E Tests
```bash
cd reports-app/frontend
npm run test:e2e # Headless mode
npm run test:e2e:headed # With browser UI
npm run test:e2e:ui # Interactive mode
```
### Telegram Bot Tests
```bash
cd reports-app/telegram-bot
pytest tests/ -v
pytest tests/ --cov=app --cov-report=html
```
**API Documentation** (when backend running):
- Swagger UI: http://localhost:8001/docs
- ReDoc: http://localhost:8001/redoc
- Health Check: http://localhost:8001/health
---
## Production Deployment
### Linux/Docker Deployment
ROA2WEB supports two deployment architectures:
### 🐧 Linux/Docker Deployment
```bash
cd roa2web
# Setup production environment
./setup_production.sh
# Deploy application
./scripts/deploy.sh
# Health check
./scripts/health-check.sh
./setup_production.sh # Initial setup
./scripts/deploy.sh # Deploy application
./scripts/health-check.sh # Health monitoring
```
See `DEPLOYMENT_GUIDE.md` for complete deployment instructions.
### Windows Server Deployment
ROA2WEB supports deployment on Windows Server with IIS:
### 🪟 Windows/IIS Deployment
**Modern Unified Workflow** (recommended):
```powershell
# On Windows Server (PowerShell as Administrator)
cd C:\path\to\roa2web\deployment\windows\scripts
# On Development Machine (WSL/Linux)
cd deployment/windows/scripts
.\Publish-And-Deploy.ps1 # Build + Transfer to server (interactive menu)
# Install
.\Install-ROA2WEB.ps1
# Deploy
.\Deploy-ROA2WEB.ps1 -SourcePath "C:\path\to\deploy-package"
# Manage services
.\Start-ROA2WEB.ps1
.\Stop-ROA2WEB.ps1
.\Restart-ROA2WEB.ps1
# On Windows Server (PowerShell as Admin)
cd deployment/windows/scripts
.\ROA2WEB-Console.ps1 # Deploy + Manage services (interactive console)
```
See `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` for details.
**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
---
@@ -342,12 +220,11 @@ BACKEND_API_URL=http://localhost:8001
## Documentation
### General
- `CLAUDE.md` - Development guide for Claude Code
### Quick Reference
- **`CLAUDE.md`** - Development guide for AI/Claude Code (architecture, common tasks, troubleshooting)
- `docs/ARCHITECTURE_SCHEMA.md` - Architecture diagrams and schemas
- `docs/MICROSERVICES_GUIDE.md` - Microservices architecture details
- `DEVELOPMENT_BLUEPRINT.md` - Detailed development plan
- `TEAM_IMPLEMENTATION_GUIDE.md` - Team implementation guide
- `ARCHITECTURE_SCHEMA.md` - Architecture diagrams
- `MICROSERVICES_GUIDE.md` - Microservices details
### Component-Specific
- `README.md` - Main application README
@@ -357,6 +234,14 @@ BACKEND_API_URL=http://localhost:8001
- `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