3. Project Structure & Deployment Model
What you commit, what is generated, and what actually runs in production in Titan Planet
Overview
Titan Planet enforces a strict separation between:
- source code (what you write and commit)
- generated build artifacts (local-only)
- final production output (what actually runs)
This separation is enforced by the .gitignore and is essential to understanding what matters in production.
Development Structure (What You See While Working)
This is the full structure you see during development.
Not everything you see here is committed or deployed.
dist/ contains the generated build artifacts.
What You Commit to Git (Source of Truth)
These files are committed and represent your real source code.
This is the only code you maintain long-term.
Generated & Ignored Files (Never Committed)
The following files are automatically generated and ignored by Git:
dist/This directory contains your bundled and optimized JavaScript targeting the pre-compiled Engine.
It is recreated on every build and must never be edited manually.
Why These Are Ignored
- They are deterministic
- They depend on your
app/files - They do not represent developer intent
What Actually Runs in Production
After running:
npm run buildTitan produces a dist/ directory, and uses the pre-compiled Engine to execute it in production globally.
Your dist/ folder acts alongside @titanpl/engine-<os>-<arch> to serve requests instantly.
Learn More About Production
How to deploy
Dive deeper into how production runtime works, deployment strategies, and configuration best practices.
Deploy on Railway / Render (GitHub → Production)
Titan projects ship with a fully production-ready Dockerfile. Railway and Render automatically detect it and handle the entire build and runtime process.
Configuration (tanfig.json)
A complete reference for all available configuration options in TitanPL.
What Does NOT Exist in Production
These never ship to production:
node_modules/app/- TypeScript source files
- Build tooling
Production runs on the bundled dist/ logic using the pre-compiled embedded engine, avoiding slow startup and compilation.
Mental Model (Very Important)
Development is file-heavy.
Production is binary-only.
- JavaScript exists only at build time
- Rust owns runtime execution
- The binary is self-contained
- Deployment is intentionally boring and predictable
Summary
- Write & commit: JavaScript/TypeScript source
- Ignore: generated
dist/folder - Run in production:
npm run starttriggers the highly optimized Gravity execution
Titan Planet’s structure removes runtime ambiguity and makes production deployment as simple and reliable as possible.