# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 🚀 Project Overview

**ROA2WEB** - Modern ERP Reports Application with FastAPI backend, Vue.js frontend, and Telegram bot interface using microservices architecture.

**Active Branch**: `v2-roa2web-fastapi`
**Main Branch**: `main` (use for PRs)
**Working Directory**: Repository root

**Quick Reference**: See `README.md` for complete setup, commands, deployment, and testing instructions.

---

## 🏗️ Architecture

### Microservices Structure
```
.
├── shared/                    # Shared components (DB pool, auth, utils)
├── reports-app/
│   ├── backend/              # FastAPI API (port 8001)
│   ├── frontend/             # Vue.js 3 UI (port 3000-3005)
│   └── telegram-bot/         # Telegram bot (port 8002 internal)
├── docs/                     # Architecture & style guides
├── deployment/               # Production deployment scripts
└── ssh-tunnel/              # SSH tunnel for Oracle DB access
```

### Key Architectural Decisions
- **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`
- **SSH Tunnel**: Required for Oracle DB connections (development/Linux) - see Database Setup
- **FastAPI Structure**: Routers in `backend/app/routers/`, schemas in `backend/app/schemas/`, Oracle stored procedures (no ORM)
- **Telegram Bot**: Standalone SQLite database for bot data, communicates with backend via HTTP API

---

## 🗄️ Database Setup

**Schema**: `CONTAFIN_ORACLE` (authentication and user management)
**Connection**: SSH tunnel required (Oracle on remote network)

### 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
```

**IMPORTANT**: Always ensure SSH tunnel is running before starting backend services.

### Environment Variables (`reports-app/backend/.env`)
```bash
# Oracle Database (through SSH tunnel)
ORACLE_USER=CONTAFIN_ORACLE
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 Integration
TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
```

**Windows Production**: Direct Oracle connection, no SSH tunnel required. Ensure `TELEGRAM_BOT_INTERNAL_API` is set for auth code management.

---

## 🔑 Authentication Flow

1. **Login**: `POST /api/auth/login` → calls `pack_drepturi.verificautilizator(username, password)`
2. **Token**: JWT includes `username`, `user_id`, `companies[]`, `permissions[]`, `exp`, `iat`, `type`
3. **Middleware**: `AuthenticationMiddleware` in `shared/auth/middleware.py` validates tokens, injects user
4. **Protected Routes**: All routes except `excluded_paths` require valid JWT

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

---

## 📝 Common Development Tasks

### Adding a New API Endpoint
1. Create router in `reports-app/backend/app/routers/your_router.py`
2. Define Pydantic schemas in `app/schemas/`
3. Use `oracle_pool.get_connection()` context manager for DB queries
4. Register router in `app/main.py`: `app.include_router(your_router, prefix="/api/your_prefix")`

**Example**:
```python
async with oracle_pool.get_connection() as connection:
    with connection.cursor() as cursor:
        cursor.execute("""
            SELECT pack_name.procedure_name(:param1, :param2)
            FROM DUAL
        """, {'param1': value1, 'param2': value2})
        result = cursor.fetchone()
```

### Adding a New Frontend Page/Component
**IMPORTANT**: Follow the established CSS architecture and design system.

**Before writing ANY CSS**: Read **`docs/ONBOARDING_CSS.md`** (5-minute quick start) → See "Documentation Index" below for complete guide list.

**Golden Rules**:
- ✅ Use global patterns first (`.roa-card`, `.roa-metric`, `.roa-badge-*`) - check `CSS_PATTERNS.md`
- ✅ Use design tokens (`var(--color-primary)`) not hardcoded values (`#2563eb`)
- ❌ Never use `:deep()` in components (use `src/assets/css/vendor/` for PrimeVue overrides)
- ❌ Never duplicate CSS (write once, use everywhere)

### 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.

**Standard Pattern** (add handler in `app/bot/handlers.py`):
```python
async def your_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    telegram_id = update.effective_user.id

    # 1. Check authentication (use helpers.py)
    user = await get_user_by_telegram_id(telegram_id)
    if not user:
        await update.message.reply_text("⚠️ Account not linked. Use /start with code.")
        return

    # 2. Check active company (use session.py)
    active_company = await get_active_company(telegram_id)
    if not active_company:
        await update.message.reply_text("⚠️ Select company first: /selectcompany")
        return

    # 3. Call backend API (use api/client.py)
    # 4. Format response (use formatters.py)
    # 5. Add tests + update MANUAL_TESTING_CHECKLIST.md
```

### Adding Shared Functionality
1. Place in `shared/{database|auth|utils}/`
2. Import using `sys.path.append()` pattern (see `backend/app/main.py:21`)
3. Add tests in `shared/tests/`

### Frontend API Integration
```javascript
// Store pattern (src/stores/yourStore.js)
import axios from 'axios';

const api = axios.create({
  baseURL: 'http://localhost:8001/api',
  headers: { 'Authorization': `Bearer ${token}` }
});

const response = await api.get('/endpoint');
```

---

## 🔒 Security

- **Git Hooks**: Security scanning in `security/install_hooks.sh`
- **Environment Files**: Never commit `.env` (use `.env.example` as template)
- **SSH Keys**: In `ssh-tunnel/secrets/` (gitignored)
- **JWT Secrets**: Generate strong secrets for production
- **Rate Limiting**: Built into auth middleware (5 requests per 5 minutes)

---

## 📚 Documentation Index

### Quick Start & Commands
→ **`README.md`** - Project overview, setup, development commands, testing, deployment

### Architecture & Planning
- `docs/ARCHITECTURE_SCHEMA.md` - Architecture diagrams and schemas
- `docs/MICROSERVICES_GUIDE.md` - Microservices architecture details
- `DEVELOPMENT_BLUEPRINT.md` - Detailed development plan

### Frontend Development
- **`docs/ONBOARDING_CSS.md`** - CSS system quick start (START HERE for new components)
- **`docs/CSS_PATTERNS.md`** - Complete CSS patterns library (cards, forms, buttons, etc.)
- **`docs/DESIGN_TOKENS.md`** - Design tokens (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
- `reports-app/frontend/README.md` - Frontend architecture and setup
- `reports-app/frontend/tests/README.md` - Playwright E2E testing guide

### Backend Development
- `reports-app/backend/README.md` - 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
- `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

### Troubleshooting
→ **`README.md`** - Common issues (SSH tunnel, backend, frontend, database)
→ **Backend**: Check `.env`, SSH tunnel status, port 8001 availability
→ **Frontend**: Clear node_modules, check Node.js version (16+), Vite auto-ports
→ **Database**: Verify SSH tunnel, Oracle listener, credentials, test `/health`

---

## 🔧 Tech Stack

**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), pytest
**Infrastructure**: Oracle Database, SSH Tunnel, Nginx (Linux prod), Docker (Linux prod), IIS + NSSM (Windows prod)

---

**For detailed information on any topic, always check the Documentation Index above first.**