Neutral TS Starter Py (AI-Ready)

Spec-Driven by Design. Modular by Nature. Parallel-Safe by Architecture. Built for Humans & AI to Ship Together.

Neutral TS Starter Py is a modular, opinionated starter kit for building Progressive Web Applications (PWA) using Python (Flask) on the backend and Neutral TS as a universal templating engine.

This project is designed to be extensible via a "plug-and-play" component architecture, allowing scalability from quick prototypes to complex applications while maintaining a clean and decoupled structure. It is AI-Ready: every architectural choice—from isolated components to specification files—is made so that AI assistants understand, generate, and modify code alongside you with deterministic results.

Project Status

This starter is in active development.

• Stable base: component loading, routing, template rendering, security headers, auth/session foundations.
• Ongoing work: broader edge-case test coverage and hardening of optional modules for production use.

Features

• Flask application factory with component-driven routing and blueprint registration.
• Modular component architecture in src/component (manifest, schema, routes, templates, static assets).
• AI-Ready by design – Self-contained components with local specifications, a global project specification, and integrated agent skills that enable AI to work safely on multiple components in parallel.
• Neutral TS templating (NTPL) with snippet composition and schema-driven data.
• Override model using custom.json and optional config/config.db (custom table) for per-component customization.
• Security defaults: CSP, host allow-list validation, trusted proxy header guard, and security headers.
• Abuse protection: form/session token flows and request rate limiting via Flask-Limiter.
• PWA support: service worker, offline page, and web manifest component.
• Internationalization (i18n) through component locale files (locale-*.json).
• Multiple data backends configured from environment (SQLite by default).
• Automated tests for app bootstrap and component behavior (pytest).

Application Architecture

The project uses a layered architecture with clear responsibilities:

1. Presentation

• NTPL templates, component CSS/JS, and static assets.

2. Application Logic

• Component routes/controllers plus request guards (security headers, host/proxy checks, access rules).

3. Data

• JSON-backed models in src/model/ and DB connectivity configured from src/app/config.py.

4. Services

• Shared utilities, environment/config loading, and i18n locale resolution.

Request Flow

HTTP Client
    ↓
Security + Host/Proxy Guards
    ↓
Flask Router + Component Blueprint
    ↓
Component Route/RequestHandler
    ↓
Model/DB Access
    ↓
NTPL Render
    ↓
HTTP Response

Prerequisites

• Python 3.10 to 3.14.
• pip (Python package manager).
• Recommended: Virtual environment (venv).

Quick Start

1. Automatic Installer (recommended)

The project includes interactive installers:

• scripts/install.sh for Linux/macOS
• scripts/install.ps1 for Windows PowerShell

Installer features:

• Fetches repository tags and lets you choose from the latest 15 versions.
• Asks for installation directory (current directory by default).
• Creates .venv and installs dependencies.
• Copies config/.env.example to config/.env.
• Generates a random SECRET_KEY.
• Generates randomized admin routes in:
  • src/component/cmp_7040_admin/custom.json as /admin-[random]
  • src/component/cmp_8100_localdev/custom.json as /local-admin-[random]
• Randomized admin routes are generated during installation as an extra hardening measure against automated scraping/scanning of default admin URLs. This is not security by itself; core protection remains authentication/authorization and rate limiting.
• Bootstraps databases with scripts/bootstrap_db.py.
• Creates an admin role user via scripts/create_user.py (asks for user data).
• Writes DEV_ADMIN_* values into config/.env for isolated localdev access.

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/FranBarInstance/neutral-starter-py/master/scripts/install.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -NoProfile -Command "iwr -useb https://raw.githubusercontent.com/FranBarInstance/neutral-starter-py/master/scripts/install.ps1 | iex"

Important: first sign-in may require the PIN generated for the created user. Keep that PIN from the installer output.

2. Manual Setup (alternative)

2.1 Clone and Configure Environment

# Create virtual environment
python -m venv .venv

# Activate environment (Linux/Mac)
source .venv/bin/activate

# Activate environment (Windows)
.venv\Scripts\activate

2.2 Create Runtime Configuration

cp config/.env.example config/.env

At minimum, set a strong value for SECRET_KEY in config/.env.

2.3 Install Dependencies

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

2.4 Run in Development with Debugging

source .venv/bin/activate

# Create/upgrade local DB schema (recommended first run)
python scripts/bootstrap_db.py

# Optional debug guard (enabled only when all conditions are met)
# 1) set DEBUG_EXPIRE and DEBUG_FILE in config/.env
#    e.g. DEBUG_EXPIRE=3600 and DEBUG_FILE=/tmp/neutral-debug.flag
export FLASK_DEBUG=1
touch /tmp/neutral-debug.flag

python src/run.py

The application will be available at http://localhost:5000 (by default).

Optional Automatic DB Bootstrap (development)

You can enable automatic schema bootstrap at app startup:

AUTO_BOOTSTRAP_DB=true

Default is false to avoid implicit schema changes in production-like environments.

Project Structure

neutral-starter-py/
├── src/
│   ├── app/                     # Flask application factory and core configuration
│   ├── component/               # MODULE COLLECTION (The most important part)
│   │   ├── cmp_7000_hellocomp/  # Example of a full component
│   │   └── ...                  # Other components (cmp_0100_*, cmp_0200_*, etc.)
│   ├── core/                    # Core utilities (request handlers, helpers)
│   ├── model/                   # Data models
│   ├── utils/                   # Utility modules
│   ├── run.py                   # Execution script for development
│   └── wsgi.py                  # Entry point for production (Gunicorn/uWSGI)
├── config/                      # General configuration files
├── docs/                        # Project documentation
├── public/                      # Public static files
├── storage/                     # Storage directory for runtime data
└── .agents/                     # AI agent resources (skills, specs)

Component Architecture

The strength of this starter lies in src/component. Each folder there is a self-sufficient module.

Basic Rules

1. Prefix: Components must start with cmp_ (e.g., cmp_5000_login).
2. Order: They load alphabetically. cmp_5005 will override cmp_5000 if there are conflicts.
3. Content: A component can have:
   • manifest.json: Metadata and base path.
   • schema.json: Configuration and customization settings.
   • route/: Python logic (Flask Blueprints).
   • neutral/: HTML templates and snippets.
   • static/: Specific assets (JS/CSS).
   • __init__.py: Component initialization.
   • .specify/: Component-level specification that defines its contract, intended behavior, and constraints — a key ingredient of the AI-Ready architecture.

Folders that do not start with cmp_ are skipped by the loader. This is used for disabled/optional components (for example _cmp_*).

Component Structure

Each component follows this structure:

cmp_component_name/
├── manifest.json      # Component metadata
├── schema.json        # Configuration and customization
├── route/             # Component-specific routes
│   ├── __init__.py
│   └── routes.py
├── neutral/           # Component templates
│   ├── component-init.ntpl
│   └── route/
│       └── root/
│           └── content-snippets.ntpl
├── static/            # Component static resources
│   ├── component.css
│   └── component.js
├── .specify/          # AI-oriented component specification
└── __init__.py        # Component initialization

For a detailed example, see the Hello Component README. For complete technical documentation on the component architecture, refer to docs/component.md.

Configuration

Configuration is handled in layers:

1. Global: Environment variables and Flask configuration.
2. Per Component: schema.json within each component.
3. Customization: custom.json allows overriding local configurations without affecting the codebase. It is ignored by git by default, with explicit repository exceptions such as the example hellocomp component.
4. Central Override DB (optional): config/config.db can store per-component JSON overrides by UUID. For overlapping keys, merge order is: base files -> custom.json -> config.db.

Boolean environment variables follow a strict rule: only true (case-insensitive) enables the flag. Any other value (false, 0, no, empty, typo) is treated as False.

Security

Security headers, CSP setup, host allow-list validation, and trusted proxy configuration are documented in:

• docs/security-csp.md

Internationalization

The application provides comprehensive internationalization (i18n) support:

• Multi-language Support: Configurable per component
• Translation Files: JSON format in component neutral/route/locale-*.json files
• Automatic Detection: Based on browser headers or user preferences
• Language Switching: Built-in language selection mechanism

Components can define their own translations in neutral/route/locale-{lang}.json files, where {lang} is the language code (e.g., en, es, fr, de).

Deployment

For production, use a WSGI server like Gunicorn pointing to src/wsgi.py:

source .venv/bin/activate
gunicorn --chdir src wsgi:application

Notes:

• Keep FLASK_DEBUG disabled in production.
• Configure SECRET_KEY, SITE_DOMAIN, SITE_URL, ALLOWED_HOSTS, and trusted proxy CIDRs in config/.env.
• For distributed deployments, configure a shared rate-limit backend (for example Redis) instead of memory://.

Testing

Run test suite:

source .venv/bin/activate
pytest -q

Component tests are located under each component folder in src/component/*/tests/, with shared fixtures in src/component/conftest.py.

Test scope evolves with the component set. Use the repository as source of truth (src/component/*/tests/ and tests/), rather than a fixed list in this README.

Tests resolve blueprint names from the component directory at runtime (bp_{component_folder}), so they remain valid if a component changes numeric prefix (for example cmp_1200_backtotop to cmp_1300_backtotop).

Documentation

For more detailed documentation, see the docs/ directory:

• docs/component.md: Complete guide on component architecture and creation.
• docs/security-csp.md: Security headers, CSP configuration, host allow-list, and proxy trust boundaries.

AI-Ready Architecture & Agentic Capabilities

Neutral TS Starter Py is built from the ground up as an AI-Ready framework. Every design decision follows three foundational principles that make the project exceptionally friendly for AI-assisted development:

1. Self-Contained Components Each component under src/component is an isolated, pluggable module with its own routes, templates, assets, and a dedicated specification (.specify/). This creates clear boundaries so AI agents can generate, modify, or repair multiple components simultaneously without side-effects.

2. Spec-Driven Development A global specification defines the project's overall contract, and every component carries its own local specification inside .specify/. These specifications act as the single source of truth, guiding AI to understand what to build before writing a single line of code—transforming ambiguous requests into deterministic, reviewable outcomes. Because each component's specification is self-contained and independent, multiple AI agents can work on different components at the same time without coordination overhead or risk of conflicting changes.

3. Integrated Skills & Utilities Agent skill definitions under .agents/skills provide standardized workflows for common tasks (component creation, template editing, testing, etc.). Combined with the technical guides in docs/, this gives AI assistants a complete map to operate reliably within the project's conventions.

The result is a collaborative environment where humans and AI agents work side-by-side, sharing the same specifications and conventions.

Example AI Prompt

When instructing an AI assistant to create a new component, you can use a prompt like the one below. The assistant will leverage the specifications and skills automatically:

Your task is to create the component component_name, which must [functional description].

Use route: /my-route

To complete this task, review:
- The global project specification (if available) and any related component specs in .specify/
- .agents/skills/manage-component/SKILL.md
- .agents/skills/manage-neutral-templates/SKILL.md
- src/component/component_name (as a component example)

Define routes dynamically if needed, following the pattern used by other components.
The specifications take precedence over the example code when decisions are needed.

This approach ensures the AI respects the intended behavior defined in the specs, while still leveraging working examples for implementation details.

Neutral TS template engine

• Rust docs
• Template docs
• IPC server
• IPC clients
• Repository
• Crate
• PYPI Package
• Examples

License

See the LICENSE file for details.

---

Bonus: Emoji-Free README