Systemic API Standardization & Interceptor Hardening

[ayushshukla1807]

GSoC 2026 Blueprint — Phase 1: Systemic API Standardization & Interceptor Hardening

Status: Active architecture blueprint, cited in my GSoC 2026 proposal (Phase 1, Weeks 1–3). This PR establishes the structural foundation before implementation begins.

Problem

The Montage API currently returns inconsistent response shapes across endpoints. Some return {status, data}, others return raw objects, and error states are non-uniform — causing the Vue frontend to defensively null-check every response and making it impossible to write reliable Axios interceptors.

Specific failure modes observed during pre-application audit:

• MontageError exceptions bypass CORS middleware (fixed in PR Fixes #357 by serializing MontageErrors natively in MessageMiddleware and hardening the round_creation API contract. #415, but root cause is the missing standard envelope)
• Frontend alertService.js cannot distinguish between a status: failure and a network-level 5xx
• Juror-facing toasts show raw Python tracebacks when the envelope is missing

Proposed Architecture

Standardize all API responses to a single envelope schema:

sequenceDiagram
    participant Vue as Vue Component
    participant Axios as Axios Interceptor
    participant MW as MessageMiddleware
    participant DAO as DAO Layer
    participant DB as Database

    Vue->>Axios: Any API request
    Axios->>MW: Forwards with auth headers
    MW->>DAO: Validated request

    alt Success path
        DAO->>DB: Query
        DB-->>DAO: Result
        DAO-->>MW: Data
        MW-->>Axios: {status: "ok", data: {...}}
    else Error path
        DAO-->>MW: raises MontageError
        MW-->>Axios: {status: "failure", errors: [...]}
    end

    Axios->>Axios: Interceptor reads status field
    Axios-->>Vue: Resolved or rejected Promise

Loading

Standard Envelope Schema (Target)

{
  "status": "ok | failure | exception",
  "data": { ... },
  "errors": ["human-readable error strings"],
  "meta": { "request_id": "...", "timestamp": "..." }
}

GSoC Deliverable Mapping

Week	Deliverable
Week 1	Audit all endpoints for schema compliance
Week 2	Patch non-conforming endpoints + update Axios interceptor
Week 3	Add integration tests for error envelope consistency

[ayushshukla1807]

I am closing this PR to reduce repository noise. The core fixes relevant to my GSoC Proposal are being manually consolidated into PR #454 and PR #415 to make it substantially easier for the maintainers to review my code. The larger concepts discussed here will be implemented incrementally and manually if my proposal is accepted.

[ayushshukla1807]

I have stripped the AI formatting from the description and reopened this PR so I can manually improve its code over the coming days, fulfilling my promise.

[ayushshukla1807]

Closing this conceptual proposal. Consolidating my Open Source footprint to prioritize high-value, locally verified bug fixes for the current review window.