Version: 3.1.0

Engineer: Ashmeet Singh

Cross-Platform Setup

Use a virtual environment so editable installs work the same way on macOS, Linux, and Windows. Do not run pip3 install -e . directly against Apple system Python; older pip versions can fall back to setup.py develop and try to write into protected system site-packages.

One-command dev install

python3 scripts/install_dev.py

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

### Troubleshooting: missing `.venv` or activation errors

If you see errors like `source: no such file or directory: .venv` or activation fails, the project virtual environment hasn't been created yet. Create and activate it with:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

If you prefer using the packaged CLI directly (without activating the venv), run the bundled script under the virtualenv python after creating it:

.venv/bin/init-app --help

If a dependency like jinja2 or django is reported missing when importing modules, activate the virtualenv and install dev requirements:

source .venv/bin/activate
python -m pip install -r requirements-dev.txt

### Windows PowerShell

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Offline or DNS-restricted environment:

python -m pip install -e .

If runtime dependencies are already installed or supplied by your own wheelhouse, install only the source package without network access:

python scripts/install_dev.py --offline-source

The dev installer also builds the native compiler. Use --skip-compiler only when a C compiler is not available on that machine.

Build the optional native C engine with:

python scripts/build_compiler.py

The compiler output is written to bin/init-app-compiler on macOS/Linux and bin/init-app-compiler.exe on Windows.

This document outlines the full capabilities of the Project Engine. The engine supports two primary flows: Interactive UI (Menu-driven) and Headless CLI (Flag-driven).

---

🕹️ 1. Build Strategies

The engine behaves differently based on the -t (type) flag:

Strategy	Behavior
auto_config	Zero-Config. Uses smart defaults for the chosen framework. Best for rapid prototyping.
standard	The Balanced Build. Generates common folder structures (routes, models, schemas).
production	Enterprise Ready. Includes full infrastructure suites (Docker, K8s) and strict folder separation.
custom	Total Control. Enables manual folder selection and individual __init__.py configuration.

---

🛠️ 2. CLI Flag Reference

Use these flags to bypass menus and automate your workflow.

Core Identity

• name: The name of your project folder.
• -f, --framework: fastapi, flask, django, others.
• -s, --server: Specify the runner (e.g., uvicorn, gunicorn, hypercorn).
• -t, --type: The build strategy (auto_config, standard, production, custom).
• --output-dir: Directory where the project folder is created. Defaults to ~/Documents.
• --here: Create the project in the current working directory.
• --path-behavior: One-off path behavior for this project: documents, current, or custom.
• --set-default-path-behavior: Save the default path behavior for future runs.
• --set-default-output-dir: Save a custom default output directory for future runs.
• --show-path-config: Show saved path behavior.
• --reset-path-config: Reset saved path behavior.

Architecture & Packages (Custom Mode)

• --folders: Manually define every directory to be created.
• --packages: Define which of those folders should be Python packages (adds __init__.py).

Data & Environment

• --db: Set the database engine (sqlite, postgres, mysql, mongodb).
• --venv: Enable virtual environment creation (y or n).

Database adapters are chosen to work cleanly in local, CI, and container environments. MySQL projects use PyMySQL by default, so generated installs do not require native mysqlclient, pkg-config, or system MySQL headers.

Infrastructure Forge

• --docker: dockerfile, docker-compose, .dockerignore.
• --github: main.yml, ci.yml, cd.yml.
• --k8s: deployment.yml, service.yml, ingress.yml.
• --jenkins: Jenkinsfile.
• --community: CONTRIBUTING.md, SECURITY.md, CHANGELOG.md.
• --package-files: setup.cfg, setup.py, MANIFEST.in.

---

🚀 3. Usage Examples

A. The "Speed Demon" (Auto-Config)

Builds a FastAPI project with SQLite and a VENV instantly.

init-app quick_api -f fastapi -t auto_config --venv y

By default, this creates ~/Documents/quick_api no matter which folder your terminal is currently in. Use --here to keep the old current-folder behavior, or --output-dir /path/to/apps for CI and DevOps scripts.

Persist your preferred default:

init-app --set-default-path-behavior current
init-app --set-default-output-dir ~/Documents/backend-apps
init-app --show-path-config

After saving a default, normal commands use it automatically:

init-app quick_api -f fastapi

B. The "Full Stack Pro" (Production)

Builds a Django + Postgres app with Docker and GitHub Actions.

init-app pro_backend -f django -t production --db postgres --docker dockerfile docker-compose --github main.yml

C. The "Architect" (Deep Customization)

The most powerful command. Manually define folders and only make src and app Python packages.

init-app bespoke_engine -f fastapi -t custom \
  --folders src app docs tests logs \
  --packages src app \
  --db mongodb --venv y

---

🧠 4. Internal Logic & Features

🐍 Selective Package Initialization

Unlike standard generators that put __init__.py everywhere, this engine uses an init_strategy map. It only converts a folder into a Python package if explicitly told to or if the framework requires it.

💉 Snippet Injection (Django)

When building Django, the engine performs "surgical" regex injections:

• Settings Patching: Automatically adds your App to INSTALLED_APPS.
• Security Injection: Moves SECRET_KEY to environment variable logic.
• DRF Integration: If DRF is detected, it injects the REST_FRAMEWORK configuration block automatically.

🛡️ UI Folder Guard

The engine contains a security layer that prevents any template rendering from writing into the ui/ directory, protecting the engine's core interface assets during a project build.

---

🏗️ 5. Directory Structure Example (Production)

Contributors are welcome to this to enhance the optimisation of this repository