Documentation Index
Overview
Neutral TS Starter Py is a modular, security-focused boilerplate for building Progressive Web Applications. It utilizes Python (Flask) for the backend and the Neutral TS for the frontend—a language-agnostic, logic-less templating engine.
Key features include:
- Component-Based Architecture: Everything is isolated and modular, allowing for easy extension and overrides.
- Layered Component Overrides: Per-component overrides can come from
custom.json and optional centralized entries in config/config.db (custom table).
- Declarative SQL: Database queries are defined in JSON files, keeping the Python codebase clean and ensuring database portability.
- Security-First Design: Built-in CSRF protection (UTOKEN/LTOKEN), secure-by-default templating, and strict Content Security Policy (CSP) integration.
- Modular Frontend: Powerful snippet-based rendering system for dynamic route content.
Document Index
The following documents provide detailed information about the system:
- README.md: This index and project overview.
- installation.md: End-to-end installation guide (automatic and manual), including
config/.env variables to review and configure.
- development.md: The main developer guide. Explains the high-level architecture, project structure, core concepts, and essential development workflows.
- developing-ai.md: AI-assisted development guide, including collaboration conventions and best practices for working with coding agents in this project.
- component.md: Deep dive into the Component System. Covers naming conventions, file structure, lifecycle, and priority/overriding rules.
- component-quickstart.md: Practical 0-to-working-component guide with the minimal steps to create, route, render, and test a new component.
- model.md: Documentation for the Data Model layer. Explains how to define and use SQL queries via JSON files and the central Model executor.
- templates-neutrats.md: Comprehensive syntax reference for the Neutral Template Engine (NTPL), including variables, control flow, snippets, and safety features.
- templates-neutrats-ajax.md: Comprehensive syntax reference for the Neutral Template Engine (NTPL), AJAX requests and responses.
- dispatcher.md: Documentation for the RequestHandler system.
- ajax-neutral-requests.md: Integration notes for AJAX requests and
Requested-With-Ajax, including behavior when using Neutral fetch vs custom JavaScript.
- translation-component.md: Translation workflow for components, including
{:trans; ... :} best practices, locale file strategy, and the translate-component skill.
- security-csp.md: Security guide for CSP, security headers, host allow-list validation, and trusted proxy boundaries.