NYZ Platform

Self-hosted personal-ecosystem hub for the NYZ ecosystem, designed to run on a Raspberry Pi 5. FastAPI + SQLite + Jinja2, no Node build step.

Stack

• Python 3.12, FastAPI, Uvicorn
• SQLite via SQLAlchemy 2.x (sync engine, light for RPi5)
• Jinja2 templates, Pillow (image processing), argon2-cffi (password hashing), itsdangerous (signed session cookies)

Layout

app/
  main.py          FastAPI application factory
  config.py        pydantic-settings, env-driven configuration
  db.py            engine / session / Base
  models.py        SQLAlchemy ORM models
  schemas.py       Pydantic request/response schemas
  security.py      argon2 hashing, signed sessions, rate limiter, require_admin
  icons.py         built-in inline SVG line-icon set
  db_init.py       schema creation + seed (python -m app.db_init)
  create_admin.py  first-run admin bootstrap CLI (python -m app.create_admin)
  routers/
    auth.py        login / logout / password change
    admin.py       /api/admin CRUD (cards, settings, icons, profile image, audit)
    public.py      public site (minimal, frontend agent owns templates)
    integration.py sub-app integration (stub — owned by another agent)
templates/         Jinja2 templates (minimal stubs)
static/            static assets
data/              SQLite DB + uploads (gitignored)
tests/             pytest suite

Setup

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Initialize the database

Creates the schema and seeds site settings + cards from the design reference:

python -m app.db_init

Create the first admin

Either set ADMIN_PASSWORD before first boot / init, or run the CLI:

python -m app.create_admin            # prompts for username + password
ADMIN_PASSWORD=secret python -m app.create_admin --username admin

Run

uvicorn app.main:app --host 0.0.0.0 --port 8000

• GET /health — liveness probe
• POST /auth/login — form login (rate limited 5/min/IP)
• /api/admin/* — admin API (session-cookie protected)

Configuration (env vars)

Var	Default	Meaning
NYZ_SECRET_KEY	dev key (change!)	signing key for session cookies
NYZ_ADMIN_PASSWORD / ADMIN_PASSWORD	—	bootstrap admin password
NYZ_DATA_DIR	./data	DB + uploads directory
NYZ_SESSION_MAX_AGE	604800	session lifetime, seconds (7 days)
NYZ_COOKIE_SECURE	false	mark session cookie Secure (set true behind HTTPS)