README.md

Docs Hub

This repo has two documentation layers:

• the root README.md explains why the project matters
• this hub explains where to go next, depending on what you want to inspect

Start Here

• Root README for the project thesis, runtime surfaces, and quick evaluation path
• Professionalism In Practice for the engineering rationale behind the codebase
• Portfolio Demo Concepts for what each major demo is proving

Architecture And Boundaries

• Project Audit
• Refactor Plan
• Auth + Sessions
• Tracing Plan
• Reference Map for docs-first source routing inside the repo

Crate Guide

• domain for business types and invariants
• app for use cases, policy, and contracts
• infra for Postgres, hashing, migrations, and repositories
• http for routing, SSE, views, and operational surfaces
• utils for shared helpers and developer tooling

HTTP Deep Dive

• http::src
• http::router
• http::handlers
• http::handlers::demo
• http::sse
• http::views
• http::views::pages
• http::views::partials

Domain And App Deep Dive

• domain::src
• domain::user
• domain::chat
• app::src
• app::user
• app::chat
• infra::src
• infra::repo
• utils::src

Frontend And Realtime Notes

• Datastar Tao
• Datastar Signals
• Datastar Expressions
• Datastar Backend Requests
• Style System Index

Release Gate

• Before downstream publish or accept steps, run bash scripts/check_publish_dry_run.sh.
• That gate includes local workspace tests, a Docker runtime build-and-boot smoke check that hits /health and then renders the live portfolio routes, and a local act -j repo-checks run against the repo CI workflow.
• The portfolio browser smoke now compares the stable portfolio routes against committed baselines by default under artifacts/visual/baseline/portfolio-smoke, so visual regressions fail the local publish gate instead of staying advisory.
• /lab stays in the smoke path for live route/assertion coverage, but its operations timeline is still treated as a volatile surface rather than a pixel-locked baseline.
• repo-checks also verifies the Docker runtime image keeps the expected /health probe and includes both curl and wget for host-platform healthchecks.
• This repo also ships a .githooks/pre-push hook for the same gate; enable it locally with git config core.hooksPath .githooks.
• To refresh the default baselines intentionally, run PORTFOLIO_SMOKE_UPDATE_BASELINE=1 bash scripts/check_portfolio_browser_smoke.sh.
• For a heavier visual pass, run PORTFOLIO_SMOKE_MODE=matrix bash scripts/check_portfolio_browser_smoke.sh, and add PORTFOLIO_SMOKE_UPDATE_BASELINE=1 when you intentionally refresh the wider matrix under artifacts/visual/baseline/portfolio-smoke.

Suggested Reading Paths

• Hiring manager

  • Root README -> Professionalism In Practice -> HTTP crate

• Senior engineer

  • Root README -> Project Audit -> domain -> app -> infra -> http

• Frontend / realtime reviewer

  • Root README -> Portfolio Demo Concepts -> http::views -> http::sse