# Research Findings

## Current State Analysis

### Strengths
- Small codebase (785 LOC) — easy to reason about
- Clear component boundaries (Core Models → Security → Resource Mgmt → HTTP API)
- Cython compilation achieves IP protection goal
- Binary-split scheme is clever security design
- E2e test suite now provides 100% endpoint coverage (18 tests, all passing)

### Weaknesses
- Thread safety gaps in the singleton and global state patterns
- Manual cryptographic operations where library functions exist
- Dead code accumulated from earlier iterations
- Hardcoded configuration values

## Change-Specific Analysis

### C01/C02: Thread Safety (main.py)

**Current**: Bare global variable + `if None` check for ApiClient singleton. Module-level globals for unlock state.

**Recommended approach**: Double-checked locking with `threading.Lock` for the singleton. Encapsulate unlock state in a class with lock-guarded accessors. These are standard Python concurrency patterns — no library changes needed.

**Alternative considered**: Using `functools.lru_cache` for singleton — rejected because it doesn't provide thread safety guarantees for the initialization side-effects (CDN config download).

### C03/C04: PKCS7 Padding (security.pyx, binary_split.py)

**Current**: Manual last-byte inspection without full padding validation.

**Recommended approach**: Use `cryptography.hazmat.primitives.padding.PKCS7(128).unpadder()` — already imported in `security.pyx`. For `binary_split.py`, integrate the library's unpadder into the streaming decryption instead of post-hoc file truncation.

**Risk**: If any existing encrypted data was produced with non-standard padding, the library unpadder will raise `ValueError` instead of silently passing. This is correct behavior — it surfaces corruption that was previously hidden.

### C05: Log Path (constants.pyx)

**Current**: Hardcoded `"Logs/log_loader_{time:YYYYMMDD}.txt"`.

**Recommended approach**: `os.environ.get("LOG_DIR", "Logs")` — minimal change, no new dependencies.

### C06: Error Handling (main.py)

**Current**: `except OSError: pass` — violates project rules.

**Recommended approach**: Import `constants` and call `constants.logerror()`. One-line fix.

**Note**: `constants` is a Cython module — `main.py` would need to import the compiled `.so`. This works because `main.py` already imports other Cython modules indirectly via `api_client`. However, `main.py` currently only imports `unlock_state` (pure Python). A simpler approach is using `loguru.logger.warning()` directly since loguru is already configured by the time `main.py` runs.

### C07/C08: Dead Code Removal

**Approach**: Straight deletion. Git history preserves everything. No behavioral risk.

## Prioritized Recommendations

| Priority | Changes | Rationale |
|----------|---------|-----------|
| 1 (critical fix) | C03, C04 | Correctness — silent data corruption on invalid padding |
| 2 (safety) | C01, C02 | Thread safety under concurrent requests |
| 3 (cleanup) | C07, C08 | Reduce cognitive load, prevent drift |
| 4 (minor) | C05, C06 | Configurability and error visibility |