Skip to content

stack-podex.md

Latest commit

 

History

History
87 lines (67 loc) · 3.75 KB

stack-podex.md

File metadata and controls

87 lines (67 loc) · 3.75 KB
Raw
trigger model_decision
description Technical stack and working conventions for Podex

Podex stack

Podex is a PowerShell 7.6 web application built on Pode, SQLite, htmx 4, and native CSS. It is not a Spernakit application and does not use the Spernakit backend or frontend layout. For a complete application that preserves these conventions, see TodoMVC-Podex.

Layout

  • podex.ps1 starts Pode and registers static, page, API, debug, and documentation routes.
  • server.psd1 holds the local server and application settings.
  • api/<domain>/<method>.ps1 contains file-based API handlers. tools/PodexRoute.psm1 maps those files to routes.
  • views/ contains Pode layouts, partials, and page components.
  • src/ItemStore.ps1 owns the CRUD data operations. src/ItemApp.ps1 maps request state and results to API or view responses.
  • src/podex.css imports the focused native styles under src/styles/; public/css/podex.css is generated by Bun.
  • SQLite files belong under data/.

Backend conventions

Use Pode route and response helpers rather than adding another web framework. Keep SQL parameterized and return useful HTTP status codes from API handlers.

Debug handlers under api/debug/ are registered only when Podex.Debug is enabled. They use the short routes /init, /clear, and /stop, and the server restricts them to loopback clients.

The runtime loads Pode 2.14.0–2.x and PSSQLite 1.x from the user's PowerShell module path. Do not bundle those modules into the Podex release without carrying their license files as well.

Browser code

htmx handles requests and swaps server-rendered Pode fragments. CRUD forms use standard form-encoded requests. The same /api/crud handlers preserve JSON responses for ordinary API clients and return HTML fragments only when HX-Request: true is present.

TypeScript modules and tooling use ES modules. Do not introduce JavaScript or CommonJS source. Browser builds compile the small modal controller to ignored JavaScript under public/ and copy htmx from the installed package. Third-party JavaScript is confined to installed packages and generated release assets.

Commands

bun install --frozen-lockfile
bun run dev
bun run start
bun run stop
bun run test
bun run check-deps
bun run check:max-lines
bun run smoke:qc
bun run release

bun run dev owns the foreground server. start and stop manage the background process. Do not start, stop, or recycle a user-owned server unless the user asks.

Each server startup moves existing root log files into a timestamped directory beneath logs/archive/ before Pode opens fresh request and error logs. Set PODEX_LOG_PATH to isolate logs for tests or managed environments.

bun run assets:clean removes generated browser CSS and JavaScript. assets:build always runs it first so obsolete files cannot survive into development or release output.

smoke:qc is the required quality gate. It checks exact dependency pins, the 300-line runtime/tooling limit, PSScriptAnalyzer, zero-warning ESLint, Pester, licenses, release packaging and public-asset closure, and Prettier.

Release and licensing

release-manifest.json is the release allowlist. Every literal /public/ asset referenced by runtime source must be represented in that allowlist. Packaging must not include node_modules, Git metadata, or a local database.

Run bun run licenses:generate after dependency changes and commit both generated license documents. bun run check:licenses verifies the full installed dependency policy while keeping the committed release documents independent of platform-specific optional build packages. The browser-delivered htmx asset carries its notice directly. Podex's native stylesheet is first-party source.