# Project export: Universal Program Translator This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: OpenAI Build Week - Tagline: UPT translates software projects like a compiler, using deterministic analysis to constrain AI generation and preserve behavior across languages and frameworks. - Devpost: https://devpost.com/software/universal-program-translator - GitHub: https://github.com/fabulousman12/universal_program_translator - Video: https://www.youtube.com/embed/dZMW4k3CSdw?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 1 GitHub contributor(s) — fabulousman12 (10 commits) ## Devpost submission (written by the team) No Devpost description available. ## README (from the GitHub repository) # Universal Program Translator (UPT) UPT is a working compiler-style project translation pipeline. It understands a complete source project, represents it as a Universal Project Representation (UPR), verifies that representation, generates a target project, compiles it, repairs affected files, and validates observable behavior. For a human walkthrough and navigation map, start with [PROJECT_GUIDE.md](./PROJECT_GUIDE.md), then use [CODEMAP.md](./CODEMAP.md) for the deeper phase-by-phase map. For the hackathon demo, MVP scope, and a ready-to-use Devpost description, see [HACKATHON_SUBMISSION.md](./HACKATHON_SUBMISSION.md). The implementation now includes deterministic discovery, parsing, analysis, capability/behavior extraction, UPR construction and verification, target planning, evidence-backed AI generation, compiler diagnostics, targeted repair, and generated-project validation. See [PROJECT_GUIDE.md](./PROJECT_GUIDE.md) for supported scope and current MVP boundaries. ## Built with Codex and GPT-5.6 Codex with GPT-5.6 helped build and test UPT's analysis, UPR, planning, generation, compliance, compiler, repair, validation, and dashboard pipeline during a seven-day build sprint. UPT's compiler frontend remains deterministic; runtime AI access is isolated behind the provider-independent `AIService`. ## Quick start From the repository root: ```powershell git clone https://github.com/fabulousman12/universal_program_translator.git cd universal_program_translator npm install npm run build npm start ``` Open `http://localhost:8787`. Frontend dependencies are checked automatically and installed only when missing. For live generation, create `.env.local` from `.env.example`, select one configured AI provider, and keep API keys out of source control. For example: ```dotenv AI_PROVIDER=gemini GEMINI_API_KEY=your_key GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta GEMINI_MODEL=gemini-3.1-flash-lite ``` Java targets require JDK 17+ and Maven 3.9+ on `PATH`. The Hono backend serves the production React build and all `/api/*` routes from this single process. Use `npm run dev` for the backend plus Vite development servers. To inspect a successful result without an API key, open [`demo-output/express-rest-mvp`](./demo-output/express-rest-mvp). It includes the generated Spring project and saved compiler/runtime reports. ## Supported environment - Tested on Windows 11 - Node.js 22 - JDK 17 or newer - Maven 3.9 or newer - Git Other platforms may work, but they are outside the verified submission claim. ## Choose a target shape Java is a language target; Spring Boot is an optional backend framework target. Choose the target according to the source project's observable role: - **Java + Spring Boot** (`framework: "spring-boot"`) for HTTP APIs, backend services, persistence, security, and realtime server applications. - **Plain Java** (`framework: "none"`) for command-line tools, libraries, and ordinary framework-free programs. This path creates a minimal Maven/JDK project and does not invent controllers, Spring annotations, or server configuration. The dashboard exposes both choices. The CLI uses Spring Boot by default for backward compatibility; pass `--framework none` for language-only translation: ```powershell npm run cli -- prepare example\javascript-basic --id plain-java-demo --framework none npm run cli -- translate example\javascript-basic --id plain-java-demo --framework none --through compile ``` ## Verified MVP translation The submission fixture is documented in [example/README.md](./example/README.md). Run its complete JavaScript-to-Spring pipeline with: ```powershell npm run cli -- translate example\express-rest-basic --id express-rest-mvp --through validate ``` Submission claim: Express/JavaScript backend to Spring Boot. The generated project compiles, starts, and passes its UPR-derived HTTP scenarios. Plain Java generation is available as an experimental language-only path; compilation is reported separately from behavioral equivalence until a deterministic CLI/library validation harness is implemented. Run repository validation with: ```powershell npm run typecheck npm test -- --run npm run build ``` ## Current pipeline usage Place an already-cloned or extracted project at `workspace/sandbox//`, then call: ```http POST /projects//discovery Content-Type: application/json { "target": { "language": "java", "framework": "spring-boot" } } ``` For a language-only Java target, send: ```json { "target": { "language": "java", "framework": "none" } } ``` The service writes Discovery artifacts to `workspace/analysis//`. Then call the parser and analysis endpoints: ```http POST /projects//parser POST /projects//analysis POST /projects//behavior POST /projects//upr POST /projects//verification POST /projects//generation-plan POST /projects//context POST /projects//prompts POST /projects//generate POST /projects//compile POST /projects//repair POST /projects//validate ``` The Parser writes UAST artifacts. The Analysis Engine writes the execution graph, semantic index, resource graph, statistics, and diagnostics. The backend reads metadata and syntax only; it never runs uploaded code or package-manager commands. ## Architectural rules - `shared/` contains domain-neutral contracts and models. - `engines/` contains pipeline-stage ports and future implementations. - `api/` contains transport concerns only. - `config/`, `utils/`, and `workspace/` provide infrastructure services. - Engine code must not depend on Hono or HTTP types. ## License UPT is available under the [MIT License](./LICENSE). ## Detected evidence (automated analysis) Indexed codebase: 253 recognized source files, 1073 KB. - CSS (language) — detected in the code - Express (technology) — detected in the code - FastAPI (technology) — detected in the code - HTML (language) — detected in the code - Java (language) — detected in the code - JavaScript (language) — detected in the code - MongoDB (technology) — detected in the code - OpenAI (technology) — detected in the code - PostgreSQL (technology) — detected in the code - Python (language) — detected in the code - React (technology) — detected in the code - Redis (technology) — detected in the code - Rust (language) — detected in the code - TypeScript (language) — detected in the code - Node.js (technology) — claimed on Devpost, not found in the code ## Codebase structure (from repository index) ### Files (120 of 325) ``` .env.example .gitignore CODEMAP.md demo-output/express-rest-mvp/pom.xml demo-output/express-rest-mvp/README.md demo-output/express-rest-mvp/reports/capability_report.json demo-output/express-rest-mvp/reports/compiler_report.json demo-output/express-rest-mvp/reports/endpoint_report.json demo-output/express-rest-mvp/reports/startup_report.json demo-output/express-rest-mvp/reports/validation_report.json demo-output/express-rest-mvp/src/main/java/com/example/app/controller/ServerController.java demo-output/express-rest-mvp/src/main/java/com/example/app/controller/TaskRoutesController.java demo-output/express-rest-mvp/src/main/java/com/example/app/dto/ServerDto.java demo-output/express-rest-mvp/src/main/java/com/example/app/dto/TaskRoutesDto.java demo-output/express-rest-mvp/src/main/java/com/example/app/dto/TaskStoreDto.java demo-output/express-rest-mvp/src/main/java/com/example/app/PackageJson6ef7a396Application.java demo-output/express-rest-mvp/src/main/java/com/example/app/service/TaskRoutesService.java demo-output/express-rest-mvp/src/main/java/com/example/app/service/TaskStoreService.java demo-output/express-rest-mvp/src/main/resources/application.yml DOCUMENTATION.md example/express-rest-basic/package.json example/express-rest-basic/src/server.js example/express-rest-basic/src/task-routes.js example/express-rest-basic/src/task-store.js example/java-basic/src/example/Invoice.java example/java-basic/src/example/InvoiceApplication.java example/java-basic/src/example/PricingService.java example/javascript-basic/main.js example/javascript-basic/pricing.js example/README.md frontend/index.html frontend/package.json frontend/src/api/client.ts frontend/src/app/App.tsx frontend/src/app/styles.css frontend/src/components/ArtifactViewer.tsx frontend/src/components/common.tsx frontend/src/hooks/useStage.ts frontend/src/main.tsx frontend/src/types/api.ts frontend/tsconfig.json frontend/tsconfig.tsbuildinfo frontend/vite.config.ts HACKATHON_SUBMISSION.md LICENSE package.json PROJECT_GUIDE.md README.md scripts/ensure-frontend-dependencies.mjs scripts/ensure-production-build.mjs src/adapters/contracts.ts src/adapters/registry.ts src/adapters/source/javascript/native-websocket-behavior-adapter.ts src/adapters/source/javascript/socket-io-behavior-adapter.ts src/ai/ai-service.ts src/ai/contracts.ts src/ai/factory.ts src/ai/models.ts src/ai/providers.ts src/ai/README.md src/api/README.md src/api/routes.ts src/application/project-pipeline-runner.ts src/cli/upt-cli.ts src/config/config.ts src/config/README.md src/container.ts src/engines/analysis/analysis-engine.ts src/engines/analysis/analyzers.ts src/engines/analysis/contracts.ts src/engines/analysis/models.ts src/engines/analysis/README.md src/engines/behavior/behavior-builder.ts src/engines/behavior/behavior-engine.ts src/engines/behavior/binder.ts src/engines/behavior/endpoint-builder.ts src/engines/behavior/models.ts src/engines/behavior/README.md src/engines/behavior/semantic-fact-extractor.ts src/engines/behavior/summary-builder.ts src/engines/behavior/uast-control-flow-extractor.ts src/engines/behavior/validator.ts src/engines/capability/capability-engine.ts src/engines/capability/models.ts src/engines/capability/resolvers.ts src/engines/compiler/compiler-engine.ts src/engines/compiler/diagnostic-parser.ts src/engines/decision/decision-compliance-engine.ts src/engines/decision/decision-ir-engine.ts src/engines/decision/java-target-inspector.ts src/engines/decision/target-constraint-translator.ts src/engines/detection/adapters.ts src/engines/detection/ai-project-verifier.ts src/engines/detection/contracts.ts src/engines/detection/models.ts src/engines/detection/project-discovery-service.ts src/engines/detection/README.md src/engines/detection/sandbox-scanner.ts src/engines/detection/translation-validator.ts src/engines/engine-registry.ts src/engines/generator/ai-generator.ts src/engines/generator/batch-compiler-error-parser.ts src/engines/generator/batch-executor.ts src/engines/generator/batch-migration-safety.ts src/engines/generator/batch-repair-response-parser.ts src/engines/generator/batch-response-parser.ts src/engines/generator/batch-writer.ts src/engines/generator/compile-checkpoint-runner.ts src/engines/generator/formatter.ts src/engines/generator/generated-project-memory.ts src/engines/generator/generation-planner.ts src/engines/generator/generation-scheduler.ts src/engines/generator/generator-engine.ts src/engines/generator/global-context-builder.ts src/engines/generator/models.ts src/engines/generator/planning/plain-java-target-adapter.ts src/engines/generator/planning/spring-boot-target-adapter.ts src/engines/generator/planning/target-planning-adapter.ts src/engines/generator/prompt-context-builder.ts src/engines/generator/README.md [205 more files omitted for size] ``` ### Dependencies - example/express-rest-basic/package.json: express@^5.1.0 - frontend/package.json: @monaco-editor/react@^4.6.0, @tanstack/react-query@^5.66.8, @types/react@^19.0.8, @types/react-dom@^19.0.3, @vitejs/plugin-react@^4.3.4, lucide-react@^0.475.0, react@^19.0.0, react-dom@^19.0.0, react-router-dom@^7.2.0, typescript@^5.7.3, vite@^6.1.0 - package.json: @hono/node-server@^1.13.8, @types/node@^22.10.5, concurrently@^9.1.2, hono@^4.6.14, openai@^6.48.0, pino@^9.6.0, tsx@^4.19.2, typescript@^5.7.2, vitest@^3.0.5, zod@^3.24.1 - tests/fixtures/capability-node/package.json: axios@^1.0.0, bcrypt@^5.0.0, jsonwebtoken@^9.0.0 - tests/fixtures/express-alias/package.json: express@4.19.2 - tests/fixtures/express-memory-boundary/package.json: express@^4.21.2 - tests/fixtures/express-native-websocket/package.json: express@^4.21.2, ws@^8.18.0 - tests/fixtures/express-redis-boundary/package.json: express@^4.21.2, redis@^4.7.0 - tests/fixtures/express-socket/package.json: express@^4.21.2, socket.io@^4.8.1 - tests/fixtures/express-websocket-shape/package.json: express@^5.1.0, ws@^8.18.0 - tests/fixtures/express/package.json: eslint@^9.0.0, express@^4.0.0, pg@^8.0.0, prettier@^3.0.0, prisma@^6.0.0, typescript@^5.0.0, vitest@^3.0.0 - tests/fixtures/fastapi/requirements.txt: fastapi@==0.115.0, uvicorn@==0.30.0 - tests/fixtures/hono/package.json: hono@^4.0.0, typescript@^5.0.0 - tests/fixtures/mongoose-schema/package.json: express@^4.21.2, mongoose@^8.9.0 - tests/fixtures/python-production/requirements.txt: fastapi@==0.115.6, uvicorn@==0.34.0 - tests/fixtures/rust-actix/Cargo.toml: actix-web@4 - tests/fixtures/rust-axum/Cargo.toml: axum@0.8 - tools/rust-parser/Cargo.toml: proc-macro2@1, quote@1, serde@1, serde_json@1, syn@2 ### Recent commits (newest first) - output change - update installer and docuemntatation - mvp ready final - mvp v2 - mvp version almost - safepoint generation - remove the stupid ahh key - fixeing the pipeline - good placr to stop , testing needed - upto point upr builer and generational planner ## Key source files (fetched from GitHub, selected and truncated for size) ### HACKATHON_SUBMISSION.md ```markdown # Universal Program Translator (UPT) ## One-line pitch UPT is a compiler-style AI translator that converts a backend project into a language-independent **Universal Project Representation (UPR)** before planning and generating a Spring Boot target project. ## The problem Moving a real backend from one ecosystem to another is more than syntax conversion. Routes, data flow, security, configuration, external libraries, database access, and project structure must remain compatible. Existing code translators often work one file at a time and lose that project-wide context. ## Our approach ```text Repository / folder -> deterministic parsing and project analysis -> UPR: a language-independent project IR -> verified target architecture decision -> dependency-aware generation plan and evidence-only prompts -> generated Spring Boot project -> decision compliance, compilation, targeted repair, validation ``` UPT keeps source understanding deterministic. AI is used only after UPR is complete: to choose an explicit target architecture, generate target code, and repair failed generated files. The AI never silently invents dependencies: every selected dependency must be backed by an approved source capability or realtime decision. ## What is working in this MVP - Folder upload and safe public HTTPS repository intake. - Static project discovery for JavaScript, TypeScript, Java, Python, and Rust. - Deterministic UAST parsers for those source languages. - Execution graph, semantic index, resources, endpoint contracts, and language-independent behavior extraction. - UPR as the downstream source of truth. - Express/Hono HTTP backend reconstruction planning for Java/Spring Boot. - Evidence-backed prompt generation, with no placeholder sections. - Pluggable AI providers through one `AIService` abstraction. - Generated-project-only compiler diagnostics, targeted repair, and startup / endpoint validation. - Redis evidence precision: `REDIS_URL`, `redis.get`, and `redis.set` are preserved as separate source facts. - Realtime UPR contracts for Socket.IO and native WebSocket events. Their triggers, payload fields, output events, and delivery scopes are carried into planned target support-file prompts. ## Current demo scope The reliable live demo is: ```text Express or Hono HTTP backend -> Spring Boot target ``` Show the generated project as an implementation of the **observable source behavior**, not as a text-identical copy. Realtime is demonstrated as project understanding and generation context: ```text Socket.IO / native WebSocket source -> UPR interaction contracts -> approved target transport decision -> Spring support-file plan and exact event prompt context ``` Do not claim end-to-end Socket.IO wire-protocol compatibility yet. Socket.IO is not identical to raw WebSocket; a Java target transport must be selected and then validated with a matching client protocol. ## Three-minute demo script 1. Start the app with `npm ru [truncated — 4532 more characters] ``` ### DOCUMENTATION.md ```markdown # Universal Program Translator (UPT) documentation UPT is a compiler-style project translator. Its validated MVP analyzes a JavaScript/Express REST backend, builds a language-independent Universal Project Representation (UPR), and generates a Java/Spring Boot project that can be compiled and validated. This document is the main setup and operating guide. For deeper navigation, see [PROJECT_GUIDE.md](./PROJECT_GUIDE.md), [CODEMAP.md](./CODEMAP.md), and [HACKATHON_SUBMISSION.md](./HACKATHON_SUBMISSION.md). ## Validated MVP scope The submission-ready path is: ```text JavaScript/Express REST backend -> deterministic compiler frontend -> Universal Project Representation -> evidence-backed generation -> Java/Spring Boot -> Maven compilation -> targeted repair -> runtime endpoint validation ``` Java, Python, Rust, TypeScript, Hono, realtime, and plain-Java paths have parser or architectural coverage, but they should not all be presented as complete behaviorally equivalent translations. Plain Java generation is currently experimental. ## Requirements - Node.js 20 or newer - npm - JDK 17 or newer for Java generation - Maven 3.9 or newer for compilation and Spring Boot validation - One configured AI provider for source generation Check the Java toolchain with: ```powershell java -version mvn -version ``` ## Installation and startup From the repository root: ```powershell git clone https://github.com/fabulousman12/universal_program_translator.git cd universal_program_translator npm install npm run build npm run start ``` Open . The root installation is required once because it installs the backend and build tools. After that, `npm start` automatically: 1. checks the declared frontend dependencies and installs only when one is missing; 2. checks for `frontend/dist/index.html` and `dist/server.js`; 3. builds the frontend and backend only when those production artifacts are missing; 4. starts the Hono server; 5. serves both the dashboard and `/api/*` from the same process. `npm run build` and `npm run dev` also ensure frontend dependencies are installed. Existing dependencies are reused without contacting the npm registry, so normal startup remains fast and works offline after installation. After changing source code, run `npm run build` explicitly before production startup. Normal repeated starts reuse the existing production build. For development, from the repository root: ```powershell npm run dev ``` The backend runs on port `8787`. Vite runs on port `5173` and proxies `/api` to the backend. ## AI provider configuration Copy `.env.example` to `.env.local` and configure one provider. Never commit a real API key. Example Gemini configuration: ```dotenv AI_PROVIDER=gemini GEMINI_API_KEY=your_key GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta GEMINI_MODEL=gemini-3.1-flash-lite AI_REQUEST_DELAY_MS=750 ``` Provider selection is environment-driven. Engines call the shar [truncated — 5883 more characters] ``` ### package.json ``` { "name": "upt-backend", "version": "0.1.0", "private": true, "description": "Universal Program Translator (UPT) compiler backend and dashboard server.", "license": "MIT", "packageManager": "pnpm@9.15.0", "type": "module", "scripts": { "install:frontend": "node scripts/ensure-frontend-dependencies.mjs", "predev": "npm run install:frontend", "dev": "concurrently -k -n backend,frontend -c cyan,magenta \"npm run dev:backend\" \"npm run dev:frontend\"", "dev:backend": "tsx watch src/server.ts", "dev:frontend": "npm --prefix frontend run dev", "prebuild": "npm run install:frontend", "build": "npm --prefix frontend run build && tsc -p tsconfig.json", "prestart": "npm run install:frontend && node scripts/ensure-production-build.mjs", "start": "node dist/server.js", "typecheck": "tsc -p tsconfig.json --noEmit", "test": "vitest run", "cli": "tsx src/cli/upt-cli.ts" }, "bin": { "upt": "dist/cli/upt-cli.js" }, "dependencies": { "@hono/node-server": "^1.13.8", "hono": "^4.6.14", "openai": "^6.48.0", "pino": "^9.6.0", "zod": "^3.24.1" }, "devDependencies": { "@types/node": "^22.10.5", "tsx": "^4.19.2", "typescript": "^5.7.2", "vitest": "^3.0.5", "concurrently": "^9.1.2" } } ``` ### frontend/package.json ``` { "name": "upt-dashboard", "private": true, "version": "0.1.0", "type": "module", "scripts": { "dev": "vite", "build": "tsc -b && vite build", "typecheck": "tsc -b --pretty false", "start": "npm --prefix .. run start" }, "dependencies": { "@monaco-editor/react": "^4.6.0", "@tanstack/react-query": "^5.66.8", "lucide-react": "^0.475.0", "react": "^19.0.0", "react-dom": "^19.0.0", "react-router-dom": "^7.2.0" }, "devDependencies": { "@types/react": "^19.0.8", "@types/react-dom": "^19.0.3", "@vitejs/plugin-react": "^4.3.4", "typescript": "^5.7.3", "vite": "^6.1.0" } } ``` ### example/express-rest-basic/package.json ``` { "name": "upt-example-express-rest-basic", "version": "1.0.0", "private": true, "type": "module", "scripts": { "start": "node src/server.js" }, "dependencies": { "express": "^5.1.0" } } ``` ### tools/rust-parser/Cargo.toml ``` [package] name = "upt-rust-parser-bridge" version = "0.1.0" edition = "2021" [dependencies] proc-macro2 = { version = "1", features = ["span-locations"] } quote = "1" serde = { version = "1", features = ["derive"] } serde_json = "1" syn = { version = "2", features = ["full"] } ``` ### tests/fixtures/fastapi/requirements.txt ``` fastapi==0.115.0 uvicorn==0.30.0 ``` ### tests/fixtures/python-production/requirements.txt ``` fastapi==0.115.6 uvicorn==0.34.0 ``` ### tests/fixtures/go/go.mod ``` module example.com/go-sample go 1.23 ``` ### tests/fixtures/rust/Cargo.toml ``` [package] name = "rust-sample" version = "0.1.0" ``` [239 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]