LegacyLens Migration Cockpit

LegacyLens is a local prototype for compatibility-first legacy migration preparation. It accepts a browser folder upload, local folder path, or bundled sample, then creates a safe migration workspace with low-token Codex context, a ready-to-use Codex prompt, migration steps, token/cost report, patch preview, risk report, and backward-compatibility gates.

What Works

• FastAPI backend with repository analysis, workspace generation, context packaging, and deterministic migration engines.
• Dependency-free static frontend with source tabs, final dashboard graphs, migration dropdown, and feedback recording.
• Browser folder upload, local path analysis for same-machine demos, and bundled sample repository for offline demos.
• Safe workspace only. The app does not mutate the original repository, push branches, open pull requests, or execute repository code.
• The backend does not run an LLM model. It uses deterministic static analysis and rule-based generation; Codex is used after export with the generated prompt/context package.

Quick UI View

These screenshots were captured from the local LegacyLens app after generating the bundled sample migration workspace.

Video demo: documents/assets/legacylens-demo.mp4

Migration Levels

LegacyLens prepares a migration workspace at three levels: version, language, and infrastructure. Each level follows the same safety-first flow:

1. Make a safe copy of the selected source.
2. Analyze files without executing repository code.
3. Detect stack signals, tests, APIs, dependencies, docs, CI, and infrastructure files.
4. Generate a migration plan, compatibility gates, risks, context gaps, patch preview, and Codex-ready context.
5. Keep the original repository untouched.

Migration level	What LegacyLens does today	Output
Version Upgrade	Detects dependency manifests, package managers, tests, APIs, frameworks, and runtime hints. If the target mentions Python or Node versions, it can preview small safe edits for known manifest/runtime files.	Upgrade checklist, compatibility gates, patch preview, Codex prompt, token report
Language Migration	Detects current source languages, API entry points, tests, and important files. It creates an adapter-based migration plan and compatibility harness for Codex to use later.	Language migration harness, step-by-step coexistence plan, risk report, Codex context
Infrastructure Migration	Detects Docker, Terraform, Kubernetes/Helm, CI files, and deployment-related signals. It creates an environment parity runbook and smoke-check workflow preview.	Infra runbook, manual smoke workflow preview, rollback-first plan, quality gates

Current Scope

LegacyLens is a migration preparation cockpit. It does not try to replace a developer, migration owner, or Codex. Its job is to gather the right context, reduce token-heavy source input into a focused package, and make migration work safer before implementation begins.

For all migration types, the current prototype:

• Uses static analysis and deterministic rules.
• Avoids executing source code from the target repository.
• Avoids changing the original repository.
• Generates reviewable artifacts instead of applying changes automatically.
• Creates a separate workspace where Codex or a developer can continue the migration.

Prototype Limits

These limits keep the local prototype responsive and predictable during demos. For larger repositories, prefer Local Path mode on the same machine because the backend can copy the folder while skipping ignored runtime/build folders instead of forcing the browser to upload every file.

Area	Current limit	Applies to	Behavior
Uploaded file count	6,000 files	Upload Folder	The static frontend and FastAPI multipart parser reject uploads above this count.
Uploaded payload size	25 MB total	Upload Folder	The API stops reading and returns 413 when the combined uploaded bytes exceed the cap.
Multipart form fields	20 non-file fields	Upload Folder	The upload parser accepts the file list plus expected metadata fields such as migration type and target requirement.
Ignored upload folders	.git, __pycache__, .pytest_cache, .venv, venv, node_modules, dist, build, target, .next, .terraform	Upload Folder	Files under these folders are skipped after upload parsing and are not copied into the generated source workspace.
Ignored copied folders	.git, .idea, .vscode, __pycache__, .pytest_cache, .venv, venv, node_modules, dist, build, target, .next, .terraform	Local Path, Sample, GitHub clone, generated workspace copy	These runtime, IDE, dependency, and build folders are skipped during safe-copy operations.
Individual source file size	1.5 MB	All analysis modes	Larger files are treated as binary, unsupported, or too large and are excluded from text analysis/context.
Repository analysis read size	8,000 characters per readable file	All analysis modes	Stack detection, inventory, APIs, tests, and notable-file detection read up to this many characters per file.
Context packaging read size	16,000 characters per readable file	Generated context package	Raw token estimates and optimized context selection read up to this many characters per readable file.
Generic context inclusion	First 12 uncategorized readable files	Generated CONTEXT.md	High-signal files are included by category; otherwise only the first generic snippets are kept to avoid noisy context.
High-signal file list in context	60 entries	Generated CONTEXT.md	The main context file lists the first 60 included files; SOURCE_INDEX.md carries the fuller included list.
Skipped/reduced file list	120 entries	Generated SOURCE_INDEX.md	The skipped/reduced section is truncated for readability.
Source snippet length	1,200 characters per notable file	Generated CONTEXT.md	Snippets from notable files are shortened before being added to the Codex context.
Public API signal count	8 signals	Repository analysis/dashboard	API route examples stop after the first 8 matches.
Notable API/test files	First 8 API files and first 8 test files	Repository analysis	These are merged with dependency, infra, and CI files to build the notable-file set.
GitHub clone depth	1 commit	GitHub URL mode	Clones are shallow to reduce demo time and disk usage.

Future Enhancement Scope

The current boundaries are intentional for a safe hackathon prototype. These areas can become stronger in future versions.

Version Upgrade

Today, LegacyLens can detect common manifests and preview limited runtime/manifest edits when the target requirement is explicit, such as Python 3.12 or Node 20.

Future enhancements:

• Add deeper dependency graph analysis for package ecosystems such as npm, pip, Maven, Gradle, NuGet, Go modules, and Cargo.
• Update lockfiles and dependency ranges in a controlled migration branch.
• Detect framework-specific upgrade rules, for example FastAPI, Django, React, Spring, Angular, or .NET.
• Run configured test commands inside a controlled sandbox and attach results to the dashboard.
• Compare API contract snapshots before and after upgrade steps.
• Generate compatibility matrices for old runtime, target runtime, dependencies, and known breaking changes.

Language Migration

Today, LegacyLens can prepare a language migration plan for many source and target combinations by detecting current language signals and generating an adapter/coexistence workflow.

Future enhancements:

• Add language-pair-specific migration playbooks, for example Java to Go, Python to TypeScript, PHP to Java, or C# to Java.
• Use AST/parser-based analysis instead of only extension and regex signals.
• Extract public contracts such as request/response models, schemas, DTOs, serialization behavior, and error formats.
• Generate characterization tests for critical business behavior before migration.
• Suggest first safe migration slices based on dependency direction and risk.
• Produce Codex prompts tailored to the exact source and target language pair.
• Support phased dual-run/parity comparison between legacy and migrated modules.

Infrastructure Migration

Today, LegacyLens can detect common infrastructure files and create a rollback-first runbook with compatibility gates.

Future enhancements:

• Build an infrastructure dependency map across Docker, CI, Terraform, Kubernetes, Helm, cloud configs, and environment variables.
• Detect ports, health checks, startup commands, secrets, volumes, network assumptions, and deployment order.
• Add cloud-specific guidance for Azure, AWS, GCP, Kubernetes, and container platforms.
• Validate environment parity between old and new infrastructure.
• Generate smoke-test workflows matched to the detected stack.
• Create rollout and rollback checklists per environment.
• Optionally prepare pull requests or deployment artifacts after human approval.

Deployment Strategy

Today, LegacyLens is designed as a local demo application where the FastAPI backend serves the static cockpit and provides the analysis APIs.

Future deployment path:

• Deploy the full FastAPI app first so the complete product works end to end from one public URL.
• Let FastAPI serve both the static frontend and backend APIs:
  • / for the LegacyLens cockpit.
  • /static/* for frontend assets.
  • /api/* for repository analysis, upload analysis, generated workspace data, feedback, and ZIP download.
• Use a cloud host that can run Python/FastAPI, such as Azure App Service, Azure Container Apps, Render, Railway, Fly.io, or a container platform.
• Use GitHub Actions for CI/CD, including backend tests and deployment.
• Use temporary server disk for hackathon demos, then move generated workspaces and ZIP files to blob/object storage for longer-lived deployments.
• Keep GitHub Pages as an optional static layer:
  • project landing page,
  • documentation site,
  • or static frontend hosted separately from the API.
• If GitHub Pages hosts the frontend, configure the frontend to call a public backend URL instead of relative /api/* routes.
• Add the GitHub Pages origin to backend CORS when using split frontend/backend hosting.
• In public cloud deployment, prefer Upload Folder and Sample modes. Local Path mode is best for same-machine demos because a cloud backend cannot read a folder path from the user's laptop.
• For public demos, avoid private repository token flows until authentication, secret handling, rate limiting, and cleanup policies are production-ready.

Simple HLD

This high-level design shows the simple LegacyLens flow from source upload to Codex-ready migration context.

flowchart LR
    A["Upload folder<br/>or choose local/sample"] --> B["LegacyLens makes<br/>a safe copy"]
    B --> C["Analyze code,<br/>docs, tests, APIs"]
    C --> D["Generate optimized<br/>CONTEXT.md"]
    C --> E["Generate ready<br/>CODEX_PROMPT.txt"]
    D --> F["Final dashboard<br/>token savings + risks"]
    E --> F
    F --> G["Download ZIP<br/>all generated files"]
    G --> H["Give prompt + context<br/>to Codex"]
    H --> I["Codex performs<br/>migration steps"]

Loading

Architecture Flow

The simple Mermaid source is available at documents/assets/legacylens-simple-flow.mmd. A detailed end-to-end Mermaid source is available at documents/assets/legacylens-end-to-end-flow.mmd, with a standalone architecture note at documents/architecture.md.

Detailed Flow

flowchart TD
    U["User selects source"] --> S{"Source type"}
    S --> UP["Upload folder"]
    S --> LP["Local path"]
    S --> SM["Bundled sample"]

    UP --> SKIP["Upload sanitizer skips ignored folders<br/>.git, node_modules, dist, build, .venv"]
    LP --> COPY["Copy local folder"]
    SM --> COPY_SAMPLE["Copy sample repo"]

    SKIP --> SAFE["Safe internal source copy"]
    COPY --> SAFE
    COPY_SAMPLE --> SAFE

    SAFE --> ANALYZE["Static repository analyzer"]
    ANALYZE --> INV["Inventory<br/>languages, frameworks, manifests, tests, APIs, docs, infra"]
    ANALYZE --> RISK["Risk and context-gap detector"]
    ANALYZE --> STACK["Stack and command detection"]

    INV --> PLAN["Deterministic migration engine"]
    RISK --> PLAN
    STACK --> PLAN

    PLAN --> GATES["Quality gates and migration steps"]
    PLAN --> PATCH["Patch preview / runbook artifact"]

    SAFE --> WORKSPACE["Migration workspace<br/>workspaces/{project_id}"]
    WORKSPACE --> SRC["source/<br/>copied repo only"]
    WORKSPACE --> GEN["generated/"]
    WORKSPACE --> REPORTS["reports/"]

    GATES --> CONTEXT["Context package generator"]
    PATCH --> CONTEXT
    INV --> CONTEXT
    RISK --> CONTEXT

    CONTEXT --> TOKENS["Token optimizer<br/>raw estimate vs optimized context"]
    CONTEXT --> MD["CONTEXT.md"]
    CONTEXT --> PROMPT["CODEX_PROMPT.txt"]
    CONTEXT --> STEPS["MIGRATION_STEPS.md"]
    CONTEXT --> SOURCE_INDEX["SOURCE_INDEX.md"]
    TOKENS --> TOKEN_REPORT["TOKEN_REPORT.md"]

    MD --> GEN
    PROMPT --> GEN
    STEPS --> GEN
    SOURCE_INDEX --> GEN
    TOKEN_REPORT --> GEN
    PATCH --> GEN
    GATES --> REPORTS
    RISK --> REPORTS

    GEN --> ZIP["Generated ZIP download"]
    REPORTS --> ZIP

    GEN --> DASH["Final Dashboard"]
    REPORTS --> DASH
    TOKENS --> DASH
    GATES --> DASH
    RISK --> DASH

    DASH --> OUT["User deliverables<br/>dashboard + ZIP + workspace path"]
    OUT --> CODEX["User gives CODEX_PROMPT.txt + CONTEXT.md to Codex"]
    CODEX --> MIGRATE["Codex performs migration in a controlled workflow"]

    MODEL["Backend model note:<br/>No LLM runs inside LegacyLens backend.<br/>FastAPI uses deterministic static analysis and rule-based generation.<br/>Codex is used after export with the generated prompt/context."]
    MODEL -. explains .-> ANALYZE
    MODEL -. explains .-> PLAN
    MODEL -. explains .-> CONTEXT

Loading

Run Backend

cd backend
python -m pip install -r requirements.txt
cd ..
python -m uvicorn backend.app.main:app --reload --port 8000

Run Frontend

python -m uvicorn backend.app.main:app --reload --port 8000

Open http://127.0.0.1:8000. The backend serves a dependency-free static cockpit from frontend/static so the demo works even when npm packages are blocked by an artifact policy.

The React TypeScript source is included under frontend/src. In an unrestricted npm environment you can run:

cd frontend
npm install
npm run dev:react

Run Tests

python -m pytest
cd frontend
npm run build

Demo Path

1. Start the backend and frontend.
2. Choose Upload Folder, Local Path, or Sample.
3. Select a migration type and keep or edit the target requirement.
4. Click Generate migration workspace.
5. Review the Final Dashboard, generated context package, migration workspace, migration plan, risks, and flight recorder.