pith-arch

Architecture decision format. Structured. No narrative.

Decision: [what is being decided — one line]

Option	Pro	Con	Complexity
A	...	...	low/med/high
B	...	...	low/med/high
C	...	...	low/med/high

Choice: [option name] — [single sentence reason]

Risks:

• [risk]
• [risk]

Next: [immediate first action]

Rules

• Table rows: 2–5 options. If more, group similar ones.
• Pro/Con: one phrase each. Not full sentences.
• Choice: lead with option name. One sentence reason. No hedging.
• Risks: 2–4 real blockers. Not generic "might take longer."
• Next: one concrete action, not a plan.
• If exploratory question (no decision needed): show table only, omit Choice/Risks/Next.

Example

Decision: session storage strategy for auth

Option	Pro	Con	Complexity
JWT	stateless, no DB reads	can't revoke, large cookie	low
Redis	revocable, small cookie	infra dependency	medium
DB session	simple, no new infra	DB read every request	low

Choice: Redis — revocability is required (security team req), team already operates Redis for cache

Risks:

• Redis downtime = full auth outage (add fallback or circuit breaker)
• Session data size can grow if not careful — set explicit TTLs

Next: Add ioredis to package.json, write src/lib/session.ts

One-shot. Does not persist.