neutral-starter-py

Neutral TS Starter Py - Developer Guide

This document is a comprehensive guide for developers looking to understand, extend, and maintain the Neutral TS Starter Py application. It covers high-level architecture, core concepts, and detailed implementation workflows.

1. Architectural Overview

The application is designed around modularity, security, and separation of concerns.

Core Philosophy

Everything is a Component: The feature set is built entirely from components (src/component/). Even core features like the template engine or themes are components.
Neutral Template Library (NTPL): A language-agnostic, secure-by-default logic-less templating engine handles the frontend.
Declarative SQL: Database interactions are defined in JSON files, keeping Python code free of hardcoded SQL strings and allowing for database portability.
RequestHandler Pattern: A central RequestHandler class mediates between Flask (HTTP handling) and NTPL (View rendering), ensuring consistent security and context setup.

The Stack

Backend: Python, Flask (Routing/WSGI).
Database: SQL (SQLite/PostgreSQL/MySQL) via the Model abstraction.
Frontend: HTML5/CSS3 (Vanilla), Neutral Templates (.ntpl).
Security: Custom Token System (UTOKEN, LTOKEN), robust Session management, CSP.

2. Project Structure

root/
├── docs/                   # Documentation
├── src/
│   ├── app/                # Application Factory & Configuration
│   │   ├── components.py   # Component Loader Logic
│   │   ├── config.py       # Global Config (Paths, Secrets)
│   │   └── ...
│   ├── component/          # MODULES LIVE HERE
│   │   ├── cmp_0200_template/ # The base layout/theme engine
│   │   ├── cmp_5100_sign/     # Example: Auth system (Login/Register)
│   │   └── cmp_7000_hellocomp/# Example: Minimal component
│   ├── core/               # Framework Core Logic
│   │   ├── prepared_request.py  # Request bootstrap (security, auth)
│   │   ├── request_handler.py   # Component route handler
│   │   ├── model.py             # Database Executor
│   │   ├── template.py          # NTPL Integration
│   │   └── session.py           # Session Handler
│   ├── model/              # SQL Definitions (JSON)
│   └── neutral/            # Global Templates (if any)
└── ...

3. Core Concepts

3.1 Component System

Components are loaded alphabetically based on their folder name (cmp_NNNN_name).

Precedence: A component loaded later can override parts of an earlier component (schemas, translations, templates).
Anatomy of a Component:
- manifest.json: Registration info (UUID, Name, Route).
- schema.json: Configuration data (menus, constants, translations).
- custom.json: Local-only overrides (never committed to git).
- config/config.db (table custom): Optional centralized per-component overrides keyed by UUID (comp_uuid) with JSON payload in value_json.
- route/: Python backend logic (Blueprints, RequestHandlers).
- neutral/: Frontend templates (.ntpl).

Override merge order:

Base files (manifest.json / schema.json)
custom.json (if present)
config.db -> custom.value_json (if present and enabled=1)

3.2 The Request Pipeline

Global before_request (PreparedRequest):
- Validates Host
- Initializes Schema, Session, User
- Evaluates security policies (auth, status, roles)
- Stores result in g.pr (Flask g object)

Flask Route: Receives HTTP request (only executes if security passed).

@bp.route("/")
def index():
    handler = HelloRequestHandler(g.pr, "", bp.neutral_route)
    return handler.render_route()

RequestHandler:
- Receives g.pr (PreparedRequest context)
- Sets CURRENT_COMP_ROUTE
- Executes business logic
- Prepares template data
Template Rendering:
- Template class renders the index.ntpl (usually from cmp_0200_template).
- index.ntpl dynamically includes the component’s content-snippets.ntpl.

3.3 Data Layer (Model)

SQL is defined in JSON files in src/model/.

File: src/model/user.json
Execution: self.model.exec("user", "get-by-login", {"login": "..."})
Transactions: Supports atomic transactions by defining an array of SQL statements in the JSON value.

4. Developer Workflow

4.1 Creating a New Component

Goal: Create a “Dashboard” component mapped to /dashboard.

Copy Template: Start from cmp_7000_hellocomp or cmp_5100_sign.
```
cp -r src/component/cmp_7000_hellocomp src/component/cmp_8000_dashboard
```
cmp_7000_hellocomp is an illustrative example component. In production, disable or remove it if you do not explicitly need it.

Configuration:

Edit manifest.json:

{
    "uuid": "dashboard_8x90s",
    "name": "Dashboard",
    "route": "/dashboard",
    ...
}

Clean up schema.json to remove old component data.

Backend Implementation:

Rename/Edit route/handler_dashboard.py:

from core.request_handler import RequestHandler
class RequestHandlerDashboard(RequestHandler):
    def _pre_process(self):
        # Add custom logic here
        self.view.set_data("dashboard_stats", {"users": 100})

Update route/routes.py:

from flask import g

@bp.route("/")
def index():
    # "root" folder in neutral/route/
    handler = RequestHandlerDashboard(g.pr, "", bp.neutral_route)
    return handler.render_route()

Frontend Implementation:
- Edit neutral/route/root/content-snippets.ntpl.
- Crucial: You must define current:template:body-main-content.
```
{:snip; current:template:body-main-content >>
    <h1>Dashboard</h1>
    <p>Users: {:;dashboard_stats->users:}</p>
:}
{:^;:}
```

4.2 Handling Forms

Inherit from FormRequestHandler (see src/core/request_handler_form.py and cmp_5100_sign).

Form Handler:

class MyFormHandler(FormRequestHandler):
    def form_post(self) -> bool:
        if not self.validate_post("ref:my_form_error"): return False
        # Process data...
        return True

Template: Use {:snip; form-start :}, {:snip; form-end :} and input snippets provided by the theme or form component.

4.3 Database Interactions

To add a new query:

Create src/model/dashboard.json.

{
    "get-stats": {
        "@portable": "SELECT COUNT(*) as count FROM user"
    }
}

Call it in Python:

stats = self.model.exec("dashboard", "get-stats", {})

4.4 Using Neutral Templates (NTPL)

Snippets: Reusable blocks. {:snip; name >> content :} to define, {:snip; name :} to call.
Conditionals: {:filled; var >> show :}.
Variables:
- {:;varname:}: Output variable.
- {:;local::varname:}: Output from local (inheritable) scope.
- {:trans; key :}: Translate string.
Includes: {:include; file.ntpl :}.

Refer to docs/templates-neutrats.md for full syntax.

5. Security & Best Practices

Do NOT write SQL in Python. Always use src/model/*.json.
Use Context: All user input (POST, GET) is available in self.schema_data['CONTEXT']. Do not access Flask’s request object directly for data processing in templates if possible.
Naming:
- Components: cmp_NNNN_name.
- UUIDs: specific format (alphanumeric + underscore).
Tokens: The system automatically handles UTOKEN (User identity token) and LTOKEN (Link/Form token) to prevent CSRF. Ensure your forms include the necessary token fields (usually handled by form-start snippet).

5.1 Operational Security Configuration

Set and review these variables in config/.env before production deployment:

ALLOWED_HOSTS: Comma-separated host allow-list (localhost,*.example.com). Requests with non-allowed Host are rejected (400).
TRUSTED_PROXY_CIDRS: Comma-separated CIDRs for trusted reverse proxies. Forwarded headers are only honored from these sources.
WSGI_DEBUG_ALLOWED: Additional debug gate for WSGI entrypoints. Keep as false in production.
DEBUG_EXPIRE: Debug flag lifetime in seconds. 0 disables debug guard activation.
DEBUG_FILE: Guard file path used by debug activation checks. Keep unset in production unless debugging intentionally.

6. Testing

Run tests with pytest. Each component should carry its own tests.

# Test specific component
pytest src/component/cmp_7000_hellocomp/tests

This site is open source. Improve this page.