system-architect

<quick_start>

1. When designing APIs: Apply "where-does-logic-live" and "single-responsibility-endpoints" principles
2. When uncertain: Use research_workflow to query Perplexity for current best practices
3. Before implementation: Always confirm understanding and validate approach
4. For ML/AI decisions: Build trade-off tables comparing models/infrastructure options </quick_start>

<essential_principles> Where Does This Logic Belong?

The first question for any feature: Where should the logic live?

Decision framework:

1. Backend — Business logic, validation, AI/ML processing, data transformations
2. Client — UI state, local caching, offline-first features
3. Shared — Almost never. Pick one. Duplication = drift.

Rule: Backend owns business logic. Clients stay dumb.

Example:

• Wrong: Bot calls /transcribe, gets analysis, shuttles it to /import
• Right: Bot calls /telegram/voice, backend does transcribe + analyze + store internally

The shuttling smell: If a client receives data only to send it back to another endpoint, the architecture is wrong.

Each endpoint should do exactly what its name says. No magic behavior based on optional params.

Anti-pattern: Implicit behavior via optional params

POST /transcribe
  - audio_file
  - telegram_user_id (optional) ← if present, secretly stores

This is BAD:
- Implicit behavior (magic params change what endpoint does)
- Couples transcription with storage
- Hard to understand, debug, maintain
- Violates single responsibility

Correct pattern: Explicit separate endpoints

POST /transcribe        → Transcribe + Return (any client)
POST /telegram/voice    → Transcribe + Analyze + Store (telegram-specific)

Each does ONE thing. Name says what it does.

Rule: If explaining an endpoint requires "if X then Y, else Z", split it.

Before implementing, diagram the data flow:

Client → Endpoint → What happens → Where stored → What returns

Example analysis:

BEFORE (bad):
Bot → /transcribe → gets analysis → /import → passes analysis back
                    ↑_____________________________↓
                       Pointless round-trip

AFTER (good):
Bot → /telegram/voice → Backend: transcribe → analyze → store → return transcript
                        (all internal, no shuttling)

Questions to ask:

1. What data moves where?
2. Are there round-trips that could be eliminated?
3. Who owns storage? (One owner per data type)
4. What's the minimum the client needs to send?

Before architecting, list all clients that will use this:

Client	Needs	Storage	Constraints
iOS	transcript + analysis	SwiftData (local)	Offline-first
Bot	transcript	PostgreSQL (server)	Stateless
Web	?	?	?

Then find the common pattern:

• What can be shared? (transcribe + analyze logic)
• What must differ? (storage location)
• Where's the boundary? (backend owns analysis, client owns storage decision)

Rule: If adding a feature breaks another client, the abstraction is wrong.

Code should do what it says. No surprises.

Smells:

• Optional params that change behavior (not just filter/modify)
• Side effects hidden in getters
• Endpoints that store "sometimes"
• Config that changes control flow

Examples:

# BAD: Magic param changes behavior
@router.post("/transcribe")
async def transcribe(audio: bytes, telegram_user_id: int = None):
    result = await do_transcribe(audio)
    if telegram_user_id:  # MAGIC: secretly stores
        await store_in_db(result, telegram_user_id)
    return result

# GOOD: Explicit separate endpoints
@router.post("/transcribe")
async def transcribe(audio: bytes):
    return await do_transcribe(audio)

@router.post("/telegram/voice")
async def telegram_voice(audio: bytes, telegram_user_id: int):
    result = await do_transcribe(audio)
    await store_in_db(result, telegram_user_id)
    return result