roa2web-service-auto/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

Project Overview

ROA2WEB - Modern ERP Application with ultrathin monolith architecture:

• Reports Module (backend/modules/reports/) - Read-only reports from Oracle
• Data Entry Module (backend/modules/data_entry/) - Data input with approval workflow
• Telegram Bot Module (backend/modules/telegram/) - Telegram bot integration

Main Branch: main | Setup & Commands: See README.md

---

Module-Specific Instructions

Important

: Read module documentation FIRST before working on a module!

Module	Documentation	Key Points
Data Entry	docs/data-entry/DATA-ENTRY-MODULE.md	SQLModel, SQLite, workflow states
Reports	This file + README.md	Oracle read-only, caching
Telegram	docs/telegram/README.md	Bot commands, formatting

---

Quick Reference

Architecture

See docs/ARCHITECTURE-DECISIONS.md for:

• Single worker (--workers 1) - required for Telegram bot
• Ultrathin monolith rationale
• IIS deployment strategy

Starting Services

./start-prod.sh         # Backend :8001 + Frontend :3000
./ssh-tunnel-prod.sh    # Oracle DB tunnel (REQUIRED on Linux)
./status.sh             # Check services

Database

• Schema: CONTAFIN_ORACLE
• Connection: SSH tunnel required (Linux dev)
• Env: backend/.env (see backend/ENV-SETUP.md)

---

Key Rules (ALWAYS FOLLOW)

Frontend Development

Before writing CSS: Read docs/ONBOARDING_CSS.md (5 min)

• Use design tokens: var(--color-primary) not #2563eb
• Use shared CSS from src/assets/css/ - NEVER duplicate
• Check docs/CSS_PATTERNS.md for existing patterns
• Theme toggle: App has 3 modes (auto/light/dark) - test BOTH themes!

Tables:

• Use separate columns (Debit | Credit, not stacked)
• Filter buttons on separate row below filters
• Export ALL data, not just current page

Backend Development

• Place logic in services, not routers
• Use @cached decorator for ALL database queries
• Cache schema lookups separately (24h TTL)

Service pattern:

from app.cache.decorators import cached

class YourService:
    @staticmethod
    @cached(cache_type='your_data', key_params=['company_id', 'username'])
    async def get_data(company_id: int, username: str):
        # Query Oracle here

Authentication

• JWT structure: username, user_id, companies[], permissions[], exp, iat, type
• Middleware: shared/auth/middleware.py (auto-injects request.state.user)
• Rate limiting: 5 req/5 min for /auth/*

---

Documentation Index

Topic	File	Description
Setup	README.md	Commands, testing, deployment
Architecture	docs/ARCHITECTURE-DECISIONS.md	Critical decisions
CSS Quick Start	docs/ONBOARDING_CSS.md	START HERE for frontend
CSS Patterns	docs/CSS_PATTERNS.md	Cards, forms, buttons, tables
Design Tokens	docs/DESIGN_TOKENS.md	Colors, spacing, dark mode
Data Entry	docs/data-entry/DATA-ENTRY-MODULE.md	SQLModel, workflow
Telegram	docs/telegram/README.md	Bot development
Deployment	deployment/linux/README.md	Deploy from LXC

---

Learned Patterns & Known Issues

Patterns/Gotchas from previous sessions: Auto-loaded from .claude/rules/auto-build-memory.md

Known Issues & Fixes

Mobile File Upload ERR_NETWORK (Android/iOS)

Problem: File uploads fail with ERR_NETWORK (status 0) on mobile browsers.

Cause: Android/iOS browsers invalidate File object references after accessing properties due to SnapshotState in W3C File API. See Chromium Bug #40703873.

Solution: Clone the file into memory immediately after selection:

const handleFile = async (file) => {
  // FIX: Clone file to memory to avoid SnapshotState invalidation
  const arrayBuffer = await file.arrayBuffer()
  const clonedFile = new File([arrayBuffer], file.name, {
    type: file.type,
    lastModified: file.lastModified
  })
  selectedFile.value = clonedFile
}

Applied in: src/modules/data-entry/components/ocr/OCRUploadZone.vue

---

Security

• Never commit .env files
• SSH keys in ssh-tunnel/secrets/ (gitignored)
• Rate limiting in auth middleware

---

Tech Stack

Backend: FastAPI, python-oracledb, JWT, Pydantic Frontend: Vue.js 3, PrimeVue, Pinia, Vite Telegram: python-telegram-bot, SQLite, httpx Infra: Oracle DB, SSH Tunnel, IIS (Windows prod)