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, then use 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.

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 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:

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:

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. 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:

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. Run its complete JavaScript-to-Spring pipeline with:

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:

npm run typecheck
npm test -- --run
npm run build

Current pipeline usage

Place an already-cloned or extracted project at workspace/sandbox/<project-id>/, then call:

POST /projects/<project-id>/discovery
Content-Type: application/json

{ "target": { "language": "java", "framework": "spring-boot" } }

For a language-only Java target, send:

{ "target": { "language": "java", "framework": "none" } }

The service writes Discovery artifacts to workspace/analysis/<project-id>/. Then call the parser and analysis endpoints:

POST /projects/<project-id>/parser
POST /projects/<project-id>/analysis
POST /projects/<project-id>/behavior
POST /projects/<project-id>/upr
POST /projects/<project-id>/verification
POST /projects/<project-id>/generation-plan
POST /projects/<project-id>/context
POST /projects/<project-id>/prompts
POST /projects/<project-id>/generate
POST /projects/<project-id>/compile
POST /projects/<project-id>/repair
POST /projects/<project-id>/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.