Standardize your project structure and automate repetitive boilerplate generation with a professional command-line interface.

The Challenge

FastAPI is intentionally minimalist, which means it lacks a built-in project generator or application "scaffolder" like Django's startapp. This leads to: 1. Structural Inconsistency: Different projects within the same team follow different folder patterns. 2. Boilerplate Fatigue: Developers spend hours manually creating models.py, schemas.py, repositories.py, and services.py for every new domain. 3. Pathing Issues: Difficulty managing PYTHONPATH so that modular sub-apps can import each other without complex hacks. 4. Insecure Defaults: Developers often use weak, hardcoded secret keys during initial setup.

The ZCore Elegance

The zc CLI tool provides a unified command set to initialize projects, scaffold modular domain-driven apps, and launch a pre-configured development server. It enforces the ZCore architectural standards while generating cryptographically secure environment files.

# 1. Initialize a new project with secure secrets
zc init my_api
cd my_api

# 2. Scaffold a domain with full Repository/Service logic
zc startapp inventory --template

# 3. Launch the server with correct PYTHONPATH
zc run

# Standard projects require manual labor for every module:
mkdir -p inventory
touch inventory/__init__.py inventory/models.py inventory/services.py
# (Open editor, manually write 100+ lines of CRUD boilerplate)
# (Manually manage .env and secret generation)
# (Manually run uvicorn with path overrides)
PYTHONPATH=. uvicorn main:app --reload

Boundaries & Integration

The CLI is a developer productivity tool, not a runtime dependency.

• Standard Python Output: Every file generated by zc is a standard .py file based on the templates in zcore.cli.templates. You can delete the CLI and your project will continue to function perfectly.
• Uvicorn Wrapper: The zc run command is a wrapper around subprocess.run calling uvicorn. It reads the HOST and PORT directly from your .env file to ensure the CLI environment matches your application settings [cli/commands.py].
• Plugin Registration: After running startapp, ZCore reminds you to register the generated Plugin in your Kernel. The CLI does not "magically" modify your main.py code to prevent accidental corruption of your project logic.

Under-the-Hood Spec

1. Cryptographically Secure Secret Generation

The zc init and zc gensecret commands use the secrets module (specifically secrets.token_hex(32)) [cli/commands.py]. This ensures that every ZCore project starts with a unique, high-entropy 64-character secret key, mitigating common production vulnerabilities caused by weak default keys.

2. Dynamic PYTHONPATH Injection

Modular applications often fail to resolve imports when running via raw python or uvicorn. The zc run command dynamically modifies the execution environment by setting env["PYTHONPATH"] = "." [cli/commands.py]. This ensures that your modular plugins can use clean, absolute imports (e.g., from inventory.models import Stock) regardless of the current working directory.

3. Identifier & Path Validation

Before creating any files, the CLI validates that the project and app names are valid Python identifiers using name.isidentifier() [cli/main.py]. It also utilizes pathlib for strict collision checks, preventing the CLI from overwriting existing files if a developer runs a scaffolding command by mistake.