Project Structure

Project Architecture & Deep Structure 🏗️

Urja is built on a modular "Governance-First" architecture that separates the core build engine from the framework-specific adapters and the AI-driven DX layer.

1. Core Engine (/src/core/engine)

The heart of Urja is a 10-Stage Pipeline Orchestrator designed for maximum parallelism and determinism.

Stage	Name	Responsibility
Stage 1	Initialization	Path normalization, environment loading, and context freezing.
Stage 2	Input Fingerprinting	Recursive hashing of all input files for CI verification and cache invalidation.
Stage 3	Graph Attachment	Loading or constructing the absolute dependency graph.
Stage 4	Build Planning	Calculating chunk boundaries and asset groupings.
Stage 5	Execution Planning	Designing the parallel worker schedule for Stage 7.
Stage 6	Determinism Check	Verifying that the plan will produce a consistent hash.
Stage 7	Parallel Execution	The heavy lifting. Concurrent transformation and module definition.
Stage 8	Optimization	Tree shaking, artifact minification, and CSS extraction.
Stage 9	Emit	Atomic writing of artifacts to the file system.
Stage 10	Output Fingerprinting	Final build hash generation for remote caching.

2. Universal Transformation Layer (/src/core/universal-transformer.ts)

Unlike traditional meta-frameworks, Urja uses a version-agnostic transformer. This logic dynamically detects the installed version of a framework (e.g., React 17 vs 18, Vue 2 vs 3) and applies the correct transformation presets without requiring user-side configuration change.

3. Dependency Resolution & Graph (/src/resolve)

The resolver handles the complex logic of mapping specifiers to physical files.

• Cross-Platform Normalization: Custom logic to ensure C:\path and /path result in the same deterministic module IDs.
• Incremental Invalidation: When a file changes, only the strictly affected nodes in the graph are purged and re-scanned.

4. Development Synchronization (/src/dev & /src/runtime)

The dev experience is powered by a WebSocket-driven sync engine:

• DevServer: A high-performance server supporting HMR, proxying, and the Live Config API.
• LiveConfigManager: A secure state-management class that allows updating build parameters on-the-fly without a server restart.

5. AI & Governance Layer (/src/ai & src/audit)

• Telemetry: Fine-grained metric collection for every build stage.
• AI Healer: Intercepts build errors and matches them against a "Fix Store" to suggest autonomous repairs.
• Governance Mode: Enforces architectural boundaries (e.g., preventing internal imports from leaking into public plugins).