You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> **Agentic legacy-code migration with program analysis, dependency intelligence, Qdrant-backed retrieval, migration planning, and post-migration QA.**
3
+
> **Agentic legacy-code migration with program analysis, dependency intelligence, Qdrant-backed retrieval, migration planning, context-grounded conversion, and post-migration release gates.**
4
4
5
5
LegacyLens analyzes a legacy repository, builds a structured representation of its codebase, creates a migration plan, performs context-grounded code transformation, and evaluates the resulting target project with deterministic engineering checks.
6
6
7
-
The design deliberately combines **deterministic program analysis** with **probabilistic LLM reasoning** instead of sending an entire repository to a model in one prompt.
The task lifecycle is explicitly bound to its backend task ID so workflow progress events can update the task being polled by the UI.
20
25
21
26
```text
22
-
Legacy repository → LLM → generated repository
27
+
Migration request
28
+
↓
29
+
Task created + bound
30
+
↓
31
+
Scanner / planning / conversion progress
32
+
↓
33
+
Task status endpoint
34
+
↓
35
+
Live migration workspace
23
36
```
24
37
25
-
That approach breaks down on real repositories because of context limits, missing dependencies, inconsistent transformations, hallucinated APIs, and weak validation.
The migration platform now has stronger failure handling around the hosted LLM gateway and artifact generation:
46
41
47
-
-**Deterministic analysis before generation:** AST, symbols, dependencies, and technology signals ground the agents.
48
-
-**Bounded retrieval instead of giant prompts:** analysis artifacts are stored remotely and retrieved selectively.
49
-
-**Qdrant Cloud instead of an embedded vector database:** hosted retrieval avoids local database/model baggage in the Render deployment path.
50
-
-**Planning before conversion:** target structure and symbol mappings are established before generation.
51
-
-**Language-agnostic validation:** execution contracts and toolchain validation are resolved through language/target adapters rather than hard-coded Java/Python rules.
52
-
-**QA after generation:** conversion is treated as an engineering workflow with measurable structural and executable checks.
42
+
-Gateway rate-limit failures are surfaced as real migration failures rather than fabricated code.
43
+
-Invalid/empty model output is rejected instead of being treated as generated source.
44
+
-Directory-like output paths are normalized defensively.
45
+
-Release readiness is derived from the post-migration quality gate.
46
+
-A blocked/failed migration can still produce a clearly labeled failure report when no valid migration artifact exists.
47
+
-Hosted execution can use lightweight workflow settings to reduce unnecessary agent-event retention.
53
48
54
49
## Architecture
55
50
56
51
```text
57
-
┌──────────────────────┐
58
-
│ Streamlit UI │
59
-
│ upload / progress / │
60
-
│ reports / chat │
61
-
└──────────┬───────────┘
62
-
│ HTTP
63
-
▼
64
-
┌──────────────────────┐
65
-
│ FastAPI │
66
-
│ API + task lifecycle │
67
-
└──────────┬───────────┘
68
-
│
69
-
▼
70
-
┌──────────────────────┐
71
-
│ Workflow Orchestrator │
72
-
└──────────┬───────────┘
73
-
│
74
-
┌────────────────────┼────────────────────┐
75
-
▼ ▼ ▼
76
-
Repository Qdrant Cloud Planning
77
-
Scanner Knowledge Base Agent
78
-
│ │ │
79
-
AST / CTags dense + sparse mappings / goals
80
-
dependencies metadata filters target structure
81
-
└────────────────────┼────────────────────┘
82
-
▼
83
-
Conversion Agents
84
-
│
85
-
▼
86
-
Target Repository
87
-
│
88
-
▼
89
-
Post-Migration QA
90
-
│
91
-
Release Gate
52
+
Legacy Repository
53
+
↓
54
+
Program Analysis
55
+
AST / CTags / dependencies / stack detection
56
+
↓
57
+
Knowledge Base
58
+
Qdrant + metadata-aware retrieval
59
+
↓
60
+
Migration Planning
61
+
target architecture + symbol/file mapping
62
+
↓
63
+
Agentic Conversion
64
+
context-grounded transformations
65
+
↓
66
+
Post-Migration QA
67
+
structural + executable validation
68
+
↓
69
+
Release Gate
70
+
ready / blocked / review
71
+
↓
72
+
Migration artifact or failure report
92
73
```
93
74
94
75
## Core capabilities
95
76
96
-
### Repository intelligence
97
-
98
77
- Multi-language source scanning
99
78
- AST / tree-sitter analysis
100
79
- Universal CTags symbol extraction
101
80
- File and symbol dependency analysis
102
-
- Technology and framework detection
103
-
- Complexity and structural signals
104
-
105
-
### Knowledge engineering
106
-
107
-
- Lossless analysis-artifact chunking
108
-
- Metadata-aware retrieval
109
-
- Source/target context separation
110
-
- Qdrant Cloud vector storage
111
-
- Hosted dense and sparse embedding inference
112
-
- Token-bounded context construction
113
-
114
-
### Agentic migration workflow
115
-
116
-
- Scanner agent
117
-
- Knowledge-base agent
118
-
- Migration planning agent
119
-
- Conversion agent
120
-
- Post-migration analysis
121
-
- Conversational access to migration artifacts
81
+
- Technology/framework detection
82
+
- Qdrant-backed analysis retrieval
83
+
- Planning before conversion
84
+
- Agentic code transformation
85
+
- Deterministic post-migration QA
86
+
- Release gates and repair loops
87
+
- Evidence-backed migration reports
88
+
- Ask-the-codebase retrieval over migration artifacts
122
89
123
-
### Migration QA + Release Engineering
90
+
##BYOK / shared LLM Gateway
124
91
125
-
The target repository enters a deterministic engineering gate after generation:
126
-
127
-
```text
128
-
Generated Target
129
-
↓
130
-
Stack / toolchain detection
131
-
├── lint / format / syntax
132
-
├── type checks where available
133
-
├── dependency install when supported
134
-
├── unit tests
135
-
└── build / compile / execution checks
136
-
↓
137
-
Failure?
138
-
├── No → Release Gate → package
139
-
└── Yes → bounded repair loop → re-run gates
140
-
```
141
-
142
-
Execution-contract handling and target-toolchain validation are language-agnostic. A target adapter determines the appropriate entry-point and validation strategy for the detected ecosystem.
143
-
144
-
A green gate means the generated project passed the configured executable checks for its detected ecosystem; it is **not** a mathematical proof of semantic equivalence.
145
-
146
-
## BYOK / LLM integration
147
-
148
-
LegacyLens uses the shared Portfolio LLM Gateway for portfolio sessions.
92
+
LegacyLens uses the portfolio's shared LLM Gateway for request-scoped inference sessions.
149
93
150
94
```text
151
95
Portfolio BYOK
152
96
↓
153
-
Redis-backed session
154
-
↓
155
-
Short-lived JWT
97
+
Short-lived gateway session
156
98
↓
157
99
LegacyLens
158
100
↓
159
101
Portfolio LLM Gateway
160
102
↓
161
-
User-selected provider/model
103
+
Selected provider / model
162
104
```
163
105
164
-
The application receives a temporary gateway session token. Provider API keys remain server-side.
106
+
Provider credentials remain outside the project frontend/source repository.
165
107
166
108
## Local development
167
109
@@ -170,29 +112,17 @@ cp .env.example .env
170
112
docker compose up --build
171
113
```
172
114
173
-
Typical local endpoints are exposed by the compose configuration for the UI, API, and Swagger interface.
174
-
175
115
## Testing
176
116
177
117
```bash
178
118
python -m pytest -q
179
119
python portfolio_quality/quality_gate.py .
180
120
```
181
121
182
-
## Security posture
183
-
184
-
-`.env` is ignored and credentials are environment-driven.
185
-
- Provider keys are not embedded in source code.
186
-
- Runtime/generated directories are ignored.
187
-
- Validation commands are allow-listed rather than arbitrary model-generated shell commands.
188
-
- External-impact actions are bounded by the workflow design.
189
-
190
122
## Limitations
191
123
192
-
LegacyLens is a portfolio and engineering demonstration, not a turnkey enterprise migration service. Semantic equivalence remains difficult to prove automatically, so the system exposes structural signals, execution checks, and review-oriented risk instead of pretending an LLM confidence score proves correctness.
193
-
194
-
Future production work includes durable worker queues, checkpointed execution, stronger multi-user authorization, deeper language-specific adapters, distributed tracing, and larger benchmark corpora.
124
+
LegacyLens is a portfolio and engineering demonstration, not a turnkey enterprise migration service. Semantic equivalence remains difficult to prove automatically, so the system exposes structural signals, executable checks, release gates, and review-oriented evidence rather than pretending an LLM confidence score proves correctness.
195
125
196
-
## License
126
+
## Portfolio positioning
197
127
198
-
MIT License.
128
+
**Developer modernization workbench** — program analysis, retrieval-grounded planning, agentic conversion, executable validation, and release-aware migration workflows.
0 commit comments