151 lines
7.5 KiB
Markdown
151 lines
7.5 KiB
Markdown
# P6 guides — 0pt
|
|
|
|
BACKLOG P6: 19 GUIDE-level items, all marked S (small effort), all "NU"
|
|
(safe to write now). Several have their own concrete artifact instead of a
|
|
guide entry here — see the table. This file covers the rest: real,
|
|
actionable "how to build this when it's prioritized" guidance grounded in
|
|
0pt's actual code, not generic advice that could apply to any repo.
|
|
|
|
| Control | Item | Where |
|
|
|---|---|---|
|
|
| REPO-13 | `.editorconfig` | [`.editorconfig`](../../.editorconfig) |
|
|
| ARK-14 | dependency-cruiser | [`.dependency-cruiser.cjs`](../../.dependency-cruiser.cjs), `pnpm run deps:check` |
|
|
| API-24 | deprecation policy | [`docs/api/DEPRECATION_POLICY.md`](../api/DEPRECATION_POLICY.md) |
|
|
| CD-23 | K8s manifest | [`deploy/k8s/`](../../deploy/k8s/) (reference only, not the deploy path) |
|
|
| CI-16 | `act` | [`.actrc`](../../.actrc) |
|
|
| DX-11 | Makefile | [`Makefile`](../../Makefile) |
|
|
| DX-12 | onboarding | [`ONBOARDING.md`](../../ONBOARDING.md) |
|
|
| CLI-13 | `doctor` CLI subcommand | see §1 below |
|
|
| DOC-18 | documentation site | see §2 below |
|
|
| UI-30 | PWA | see §3 below |
|
|
| IAM-19 | impersonation | see §4 below |
|
|
| PAY-11 | Hyperswitch ADR | see §5 below |
|
|
| AI-18 | assistant | see §6 below |
|
|
| OBS-21 | status page | see §7 below |
|
|
| TEST-20 | chaos testing | see §8 below |
|
|
| NET-19 | IPv6 | see §9 below |
|
|
| SCALE-13 | read replicas | see §10 below |
|
|
| OSS-10 | upstream contribution | see §11 below |
|
|
| AGENT-13 | nightly agent | see §12 below |
|
|
|
|
---
|
|
|
|
## 1. CLI-13 — `doctor` CLI subcommand
|
|
|
|
There is no CLI surface at all yet (BACKLOG P1-5 — L effort, not attempted
|
|
this pass). `pnpm run siax:doctor` / `make doctor`
|
|
(`scripts/siax-doctor.mjs`) already covers the underlying check logic
|
|
(AGENT-04). When P1-5 builds `apps/cli`, wire a `siax 0pt doctor` subcommand
|
|
that shells out to (or re-imports) `scripts/siax-doctor.mjs` rather than
|
|
re-implementing the checks — one source of truth for "is this repo
|
|
compliant", not two that can drift.
|
|
|
|
## 2. DOC-18 — documentation site
|
|
|
|
Not built. When prioritized: `contracts/openapi.yaml` already exists as a
|
|
real OpenAPI 3.1 SSOT, so the lowest-effort path is a static OpenAPI
|
|
renderer (e.g. Redocly CLI or Scalar) pointed at that file, deployed as a
|
|
static site — not a hand-authored docs site that would drift from the
|
|
contract. `docs/*.md` could be published alongside via any static-site
|
|
generator that reads plain Markdown (Docusaurus, Starlight); pick whichever
|
|
matches what other SIAX Cloud repos already use, per BACKLOG's "one tool per
|
|
job" rule — check `cl0ud`/`n0d` first before introducing a new one here.
|
|
|
|
## 3. UI-30 — PWA
|
|
|
|
Not built. Would need: a `manifest.json` (icons already exist at
|
|
`public/icon*.png`/`icon.svg` — reuse them, don't regenerate), a service
|
|
worker (Next.js has no built-in PWA plugin as of this repo's Next 16; a
|
|
minimal hand-written SW covering `/api/health`-style offline detection would
|
|
be more honest than a cargo-culted `next-pwa` config, given this app's
|
|
`ignoreBuildErrors: true` posture already has enough unverified surface). Low
|
|
priority — 0pt's UI is transactional (order flow, portal), not the kind of
|
|
app users install to a home screen.
|
|
|
|
## 4. IAM-19 — impersonation
|
|
|
|
Not built. Needed pattern once an admin portal exists with real customer
|
|
data: a support/admin session that can view-as a specific tenant/user,
|
|
**always** logged to AUD0 (BACKLOG P0-18 — AUD0 client exists but is
|
|
currently no-op without `AUD0_URL`) with the impersonator's real identity
|
|
attached, never silently. Do not build a "become this user" auth shortcut
|
|
without that audit trail landing first — an impersonation feature with no
|
|
audit log is a privilege-escalation bug wearing a support-tool costume.
|
|
|
|
## 5. PAY-11 — Hyperswitch ADR
|
|
|
|
**Proposed, not accepted — payments provider is explicitly gated on the
|
|
account owner's decision (BACKLOG P1-23).** This entry exists so the option
|
|
is on record, not to decide it. Hyperswitch is an open-source payment
|
|
orchestration layer (self-hostable) that could sit in front of
|
|
Stripe/Revolut/others rather than 0pt integrating each provider directly
|
|
(`lib/stripe.ts` today). Trade-off to weigh when P1-23 is actually decided:
|
|
self-hosting Hyperswitch adds an operational dependency (another service to
|
|
run/monitor) in exchange for provider-agnosticism; direct integration
|
|
(current state) is simpler but couples this repo to Stripe's specific API
|
|
shape. Not evaluated further here — that's the ADR this guide is explicitly
|
|
not writing.
|
|
|
|
## 6. AI-18 — assistant
|
|
|
|
Not built. `app/api/ai/parse` exists today as a heuristic (no model call,
|
|
per `CLAUDE.md`/`docs/02-architecture.md`'s "honest heuristic" framing) — a
|
|
real assistant feature should route through INF0 (the fleet AI gateway,
|
|
`INF0_URL` — documented target, not yet read by any code in this repo) per
|
|
the platform mandate, never a raw provider key committed here.
|
|
|
|
## 7. OBS-21 — status page
|
|
|
|
Not built. Lowest-effort honest option once `/api/health` + `/api/ready`
|
|
are actually monitored (BACKLOG P1-11, not yet wired to Prometheus/GlitchTip
|
|
per that item): a self-hosted status page (e.g. Upptime, which is
|
|
just-a-GitHub/Gitea-Actions-cron + static site, no server to run) polling
|
|
those two endpoints. Do not stand up a status page before the endpoints it
|
|
would display are meaningfully monitored — an unmonitored status page that
|
|
says "operational" is worse than no status page.
|
|
|
|
## 8. TEST-20 — chaos testing
|
|
|
|
Not built, and low-value until BACKLOG P0-12 lands (real DB/persistence —
|
|
right now there's no durable state to chaos-test; killing the process loses
|
|
nothing that wasn't already going to be lost on the next cold start). Once
|
|
persistence exists: start with the cheapest chaos test that matches 0pt's
|
|
actual documented failure mode — kill the Postgres connection mid-request
|
|
and assert `/api/ready` flips to 503 within one health-check interval (this
|
|
is now directly testable thanks to BACKLOG P0-3's real dependency probes).
|
|
|
|
## 9. NET-19 — IPv6
|
|
|
|
Not evaluated. `docs/architecture/ARCHITECTURE.md` doesn't currently record
|
|
whether the Coolify target node(s) or `0pt.app`'s DNS have AAAA records —
|
|
check `z0ne` (SIAX's own DNS product) once a real Coolify app exists for
|
|
this repo; premature to configure before there's a fleet IP to point at.
|
|
|
|
## 10. SCALE-13 — read replicas
|
|
|
|
Not applicable yet — there is no primary database in production to
|
|
replicate (BACKLOG P0-12: state lives in in-memory `Map`s, zero DB
|
|
provisioned). Revisit once P0-12 lands and real read/write load is
|
|
measured; provisioning a replica against a database that doesn't exist yet
|
|
would be pure speculation.
|
|
|
|
## 11. OSS-10 — upstream contribution
|
|
|
|
No dependency in this repo has been identified as needing a patch upstream
|
|
rather than a workaround here (checked: no local patches in
|
|
`pnpm-lock.yaml`'s `patchedDependencies`, none found). Nothing to
|
|
contribute upstream today; revisit if/when a real workaround is added for
|
|
an upstream bug — file the issue/PR there instead of carrying the
|
|
workaround silently forever.
|
|
|
|
## 12. AGENT-13 — nightly agent
|
|
|
|
`nightly.yml` already re-runs the full quality + (now blocking) security
|
|
gate daily (BACKLOG P0-16). A step beyond that — an agent that reads the
|
|
nightly failure and opens a triage PR — is AGENT-06 territory (BACKLOG P1-19
|
|
already scopes AGENT-06 as not attempted this pass: it needs real
|
|
OpenHands/Aider/SWE-agent infrastructure via INF0, which doesn't exist yet
|
|
for this repo). Do not build a bespoke nightly-agent script here ahead of
|
|
that shared infrastructure landing — it would be exactly the kind of
|
|
one-off tool the "one tool per job" rule (`CLAUDE.md` §4) warns against.
|