## ADR: Database Schema Management

Date: 2025-10-30
Status: accepted
Context:
The application requires database schema management functionality to execute SQL scripts with proper dependency ordering and provide GUI integration for schema operations. The existing system has a complex Oracle database schema defined in docs/rateloader.sql with interdependent objects (sequences, tables, views, functions, procedures).

Decision:
Implement a comprehensive database schema management system with the following components:

1. **DatabaseSchemaManager Class**: Core class for parsing SQL files, building dependency graphs, and executing schema operations
2. **DependencyGraph Class**: Manages SQL object dependencies using topological sorting
3. **SQLObject Enum and Dataclass**: Represents different types of SQL objects and their metadata
4. **DatabaseInitializationTask**: Task class for schema execution and validation
5. **GUI Integration**: New "Database Schema" tab with controls for execution, validation, and parsing

The system uses Kahn's algorithm for topological sorting to ensure proper execution order based on object dependencies.

Consequences:
Positive:

- Automated dependency resolution prevents execution order issues
- GUI integration provides easy access to schema management
- Validation capabilities ensure schema integrity
- Extensible design allows for future enhancements like schema generation from data models

Negative:

- Parsing complex SQL files may have edge cases with advanced Oracle syntax
- Dependency extraction relies on pattern matching which may miss complex relationships
- GUI operations are synchronous and may block the interface during long operations

Alternatives:
A) Manual execution order specification: Rejected due to maintenance burden and error-proneness
B) Use external SQL parsing libraries: Rejected due to Oracle-specific syntax complexity
C) Database-native dependency resolution: Considered but rejected due to need for file-based parsing

Links:

- Implementation: core/database_schema.py
- Task integration: core/tasks.py
- GUI integration: gui/app.py
- Schema file: docs/rateloader.sql

## ADR: Task-Based Schema Operations

Date: 2025-10-30
Status: accepted
Context:
Schema operations need to be integrated into the existing task queue system to ensure proper error handling, logging, and asynchronous execution alongside other application tasks.

Decision:
Extend the task system with DatabaseInitializationTask that supports both schema execution and validation modes. The task integrates with the existing queue infrastructure and provides detailed progress reporting.

Consequences:
Positive:

- Consistent error handling and logging across all operations
- Asynchronous execution prevents GUI blocking
- Progress tracking and status reporting
- Integration with existing task monitoring

Negative:

- Additional complexity in task management
- Potential for long-running tasks to impact queue performance

Alternatives:
A) Synchronous GUI operations: Rejected due to potential for blocking the interface
B) Separate background service: Rejected due to increased complexity and resource usage

Links:

- Task implementation: core/tasks.py
- Queue system: core/task_queue.py

## ADR: JSON Wire Format Evolution (PriceExport → RateLoader)

Date: 2025-11-27
Status: accepted

**Context**:
Analysis revealed discrepancy between docs/price_exchange_with_fidelio_v8.md (specifying {"prices": [...]}) and production code in features/price_export.py (sending raw JSON array [...] from batched m_hlpricejson outputs). Code behavior validated through testing/production usage as functional source of truth.

**Decision**:
Accept code as specification:

- Raw JSON array [ {price objects} ] without "prices" wrapper
- Batching: Accumulate daily m_hlpricejson arrays until ~1MB, send as single POST
- Updated docs/PRD.md and price_exchange_with_fidelio_v8.md to match code

**Consequences**:
Positive:

- Matches validated production behavior
- Batching reduces API calls (365→~12/year), improves performance
- Documentation now reflects reality, reduces future confusion

Negative:

- Breaks legacy spec assumption of per-day {"prices": [...]}
- RateLoader must parse direct array (already does per code review)

**Alternatives**:
A) Change code to match old spec: Rejected - breaks working production, requires RateLoader changes
B) Hybrid (per-day with wrapper): Rejected - loses batching benefits
C) Update RateLoader spec only: Partial - full doc sync needed for coherence

**Links**:

- Code: features/price_export.py (batch logic, json.dumps(current_batch_data))
- Updated docs: docs/price_exchange_with_fidelio_v8.md (§2 updated), docs/PRD.md (§2.2)
- Tests: test_price_export.py (validates batching)
