roa2web-service-auto/docs/ARCHITECTURE-DECISIONS.md

# Architecture Decision Records (ADR)

This document records important architectural decisions made during ROA2WEB development.

---

## ADR-001: Ultrathin Monolith Architecture (2025-12-24)

**Status:** Accepted

**Context:**
Originally designed as separate microservices (Reports, Data Entry, Telegram Bot as independent services).

**Decision:**
Consolidated into **ultrathin monolith** - single FastAPI application with modular structure.

**Consequences:**
- ✅ Single Windows service to manage
- ✅ Shared database connection pool
- ✅ Simpler deployment
- ✅ Lower memory usage
- ✅ Easier debugging
- ⚠️ Requires careful module isolation

**Implementation:**
- All modules under `backend/modules/`
- Single `ROA2WEB-Backend` service
- Module enable/disable via `.env` flags

---

## ADR-002: Single Worker Configuration (2025-12-29)

**Status:** Accepted

**Context:**
Telegram bot integration causes conflicts when multiple uvicorn workers run simultaneously. Each worker spawns its own bot instance, but Telegram API allows only ONE bot to poll for updates.

**Problem:**
```
telegram.error.Conflict: terminated by other getUpdates request
```

**Decision:**
**Always use `--workers 1` for the unified backend service.**

**Rationale:**
1. **Telegram Bot Requirement:** Single bot instance only
2. **SQLite Cache:** Multiple workers cause locking conflicts
3. **Performance:** Async I/O means single worker handles 100+ concurrent requests
4. **Resources:** Lower memory (~400 MB vs ~1.6 GB with 4 workers)

**Consequences:**
- ✅ Telegram bot works perfectly
- ✅ No SQLite cache conflicts
- ✅ Cache stats endpoint works (no 502 errors)
- ✅ Lower memory usage
- ✅ Same performance (I/O bound, not CPU bound)
- ⚠️ Cannot scale horizontally with multiple processes

**Implementation:**
- Configured in NSSM: `--workers 1`
- NOT configurable in `.env`
- Documented in `TELEGRAM-BOT-DEPLOYMENT.md`

**Alternatives Considered:**
- Separate bot service: More complexity, no significant benefit
- Redis pub/sub for bot: Over-engineering for current scale

**Performance Characteristics:**
- Concurrent users: 100+
- Requests per minute: 1000+
- Response time: 50-200ms (DB query time)
- Adequate for: 50-100 concurrent users

---

## ADR-003: IIS Sub-Application Deployment (2025-12-29)

**Status:** Accepted

**Context:**
Application deployed at `/roa2web` path on IIS, not at root.

**Decision:**
Use Vite `base: '/roa2web/'` and axios `baseURL: import.meta.env.BASE_URL + 'api'` for all frontend API calls.

**Consequences:**
- ✅ Works correctly on production sub-path
- ✅ Works correctly on development root path
- ⚠️ All axios instances must use BASE_URL
- ⚠️ Router must use base path

**Implementation:**
- `vite.config.js`: `base: process.env.NODE_ENV === 'production' ? '/roa2web/' : '/'`
- All `axios.create()`: `baseURL: import.meta.env.BASE_URL + 'api/...'`
- IIS `web.config`: Reverse proxy rules for `/api/*` → `localhost:8000`

---

## ADR-004: Pydantic v2 Migration (2025-12-29)

**Status:** In Progress

**Context:**
Pydantic v2 changed `schema_extra` → `json_schema_extra`.

**Decision:**
Update all models incrementally to use `json_schema_extra`.

**Implementation:**
- ✅ `backend/modules/reports/models/trial_balance.py` updated
- ✅ `backend/modules/data_entry/schemas/ocr.py` already correct
- ⚠️ Warning eliminated in logs

---

## ADR-005: Web.config as Static File (2025-12-29)

**Status:** Accepted

**Context:**
IIS requires `web.config` for URL rewrite rules, but it wasn't consistently deployed.

**Decision:**
1. Store canonical `web.config` in `deployment/windows/config/`
2. Create `Create-WebConfig.ps1` script for manual creation
3. Include in deployment package

**Consequences:**
- ✅ Consistent configuration across deployments
- ✅ Easy to recreate if deleted
- ✅ Version controlled

**Implementation:**
- Canonical: `deployment/windows/config/web.config`
- Deployed to: `C:\inetpub\wwwroot\roa2web\frontend\web.config`
- Creation script: `Create-WebConfig.ps1`

---

## Future Decisions to Document

### Pending Considerations

1. **Horizontal Scaling:**
   - If needed: Load balancer + multiple app instances
   - Alternative: Separate bot service to allow multiple workers
   - Current decision: Single worker sufficient

2. **Cache Strategy:**
   - Current: SQLite L2 cache + memory L1
   - Alternative: Redis for distributed cache
   - Decision: Keep SQLite for simplicity

3. **Database Connection Pool:**
   - Current: Shared pool across all modules
   - Sizing: 5-10 connections
   - Per-module pools: Not needed yet

---

## Decision Process

When making architectural decisions:

1. **Document the context** - Why is this decision needed?
2. **List alternatives** - What other options exist?
3. **Explain rationale** - Why this option over others?
4. **Note consequences** - What are the trade-offs?
5. **Implementation details** - How is this implemented?
6. **Reference documentation** - Where to find more details?

---

**Last Updated:** 2025-12-29