Skip to content

docs: ADR 0001 + Python backend scaffolding for single-backend migration (Phase 0)#1623

Merged
Snoww3d merged 2 commits into
mainfrom
refactor/single-backend-phase-0
Jul 2, 2026
Merged

docs: ADR 0001 + Python backend scaffolding for single-backend migration (Phase 0)#1623
Snoww3d merged 2 commits into
mainfrom
refactor/single-backend-phase-0

Conversation

@Snoww3d

@Snoww3d Snoww3d commented Jul 2, 2026

Copy link
Copy Markdown
Owner

No linked issue

Summary

Kicks off a phased architecture simplification: collapse the three-tier polyglot stack (React → .NET gateway → Python engine) into a two-service architecture — React frontend talking directly to a Python FastAPI single backend — and delete the .NET gateway.

This PR is Phase 0: the decision record plus backend scaffolding. It is additive with zero runtime behavior change — the empty routers add no endpoints, and .NET still serves the frontend exactly as before.

Why

A full-stack review (CODEBASE_REVIEW.md) confirmed the .NET Composite/Mosaic/Mast/Analysis/SemanticSearch services are HTTP proxies to the Python engine, which already owns those domains end-to-end. The gateway's only non-duplicated responsibilities are auth, MongoDB persistence (just 2 collections), job tracking + SignalR, and a storage abstraction Python already has. Astropy must stay in Python, so the natural simplification is to make Python the single backend.

Outcome of the full migration: one backend instead of two, ~44k fewer lines of C# (incl. tests), no snake_case ↔ camelCase boundary, and far fewer containers/compose files. The system stays shippable after every phase (strangler-fig).

Changes Made

  • ADR docs/architecture/adr/0001-collapse-to-python-single-backend.md — context, decision, consequences, and the 8-phase roadmap. Linked from the architecture index and mkdocs nav.
  • Scaffolding packages under processing-engine/app/: auth/, db/, library/, jobs/. Empty APIRouters wired into main.py to establish the import graph and OpenAPI tags ahead of Phases 1–3.
  • requirements.txt — adds motor (async MongoDB), pyjwt, passlib[bcrypt], bcrypt for the upcoming persistence + auth phases.
  • DocsAGENTS.md and docs/architecture/system-overview.md note the in-progress target architecture and where new backend code lives.

Test Plan

  • New Python files parse cleanly (ast.parse); router wiring is mechanically identical to the five existing routers.
  • No endpoints added — empty routers are valid to include; OpenAPI gains only the new tags.
  • Full docker exec jwst-processing python -m pytest in CI (fastapi/deps run in Docker, not in this environment).

Documentation Checklist

  • docs/architecture/ (new ADR + system-overview note)
  • No other doc updates needed for Phase 0

Tech Debt Impact

  • Existing tech debt reduced — establishes the path to remove the redundant .NET proxy tier and the duplicated storage abstraction.

Risk & Rollback

  • Risk: Minimal. Additive only; no behavior change. New deps are unused until Phase 1.
  • Rollback: Revert this commit — removes the scaffolding packages, deps, and docs with no impact on the running system.

Follow-up phases

Each lands as its own PR: (1) Mongo + Auth, (2) Library/persistence, (3) Jobs + WebSocket, (4) MAST/discovery wiring, (5) frontend cutover, (6) delete .NET, (7) infra simplification, (8) in-tier god-file cleanup.

https://claude.ai/code/session_01MWMesVhoX13SVmCcgjWrDF


Generated by Claude Code

Note: recreated from #1571, which was auto-closed when its head branch was renamed from claude/review-architecture-simplify-AlLg2 (disallowed prefix) to refactor/single-backend-phase-0. Includes a ruff I001 import-sort fix on the three scaffolding routers.

claude and others added 2 commits June 7, 2026 16:42
…ion (Phase 0)

Adds the architecture decision record to collapse the three-tier polyglot
stack into a two-service architecture (React frontend + Python FastAPI
single backend), deleting the .NET gateway over a phased strangler-fig
migration.

Phase 0 (additive, zero behavior change):
- ADR docs/architecture/adr/0001-collapse-to-python-single-backend.md,
  linked from the architecture index and mkdocs nav.
- Scaffolding packages under processing-engine/app/: auth/, db/, library/,
  jobs/. Empty routers wired into main.py to establish the import graph and
  OpenAPI tags without changing runtime behavior.
- requirements.txt: motor, pyjwt, passlib[bcrypt], bcrypt for the upcoming
  persistence + auth phases.
- AGENTS.md and system-overview.md note the in-progress target architecture.

https://claude.ai/code/session_01MWMesVhoX13SVmCcgjWrDF
@Snoww3d Snoww3d merged commit cf29d93 into main Jul 2, 2026
17 checks passed
@Snoww3d Snoww3d deleted the refactor/single-backend-phase-0 branch July 2, 2026 14:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants