05-architecture-and-stack

Name: 05-architecture-and-stack
Author: heymegabyte

18stars4forks

How to install 05-architecture-and-stack?

heymegabyte/claude-skills/05-architecture-and-stack

$npx -y skills add heymegabyte/claude-skills --skill 05-architecture-and-stack

Installs into the current project.

Summary

Cloudflare-first platform selection. Decision trees for Workers, D1, R2, KV, DO, Queues, Vectorize, Containers, Sandboxes, Flagship, Agent Memory, Workflows v2. Default stack, override conditions, auth, data patterns, reliability.

Files · 1

View on GitHub

SKILL.md

1	# 05 — Architecture and Stack
2
3	Default stack: `_kernel/standards.md#stack`. Override conditions below.
4
5	## Cloudflare-first decision tree
6
7	Compute: Workers (default, every HTTP/cron/queue) · Pages (static-only marketing, rare) · Containers (non-JS runtimes: Playwright headful, ffmpeg, Python ML, build orchestration) · Sandbox SDK (generated/risky code before live promotion)
8
9	State: D1 (default relational, ≤10GB/db, Sessions API read-replicas, Time Travel 30-day PIT) · KV (eventually-consistent, cache/sessions/feature-flags) · R2 (object storage, lifecycle Standard→IA after 30d) · Durable Objects (coordination + strongly-consistent SQLite storage since Apr 2025, chat rooms/builder sessions/rate-limiting) · Hyperdrive (front external Postgres/MySQL) · Vectorize (semantic search/RAG, 5M dim/index, topK 100, 10 metadata indexes)
10
11	Async: Queues (best-effort, 5000 msg/sec, R2 event notifications) · Workflows v2 (deterministic, 50K concurrent, 300 creates/sec, 2M queued/workflow, `step.do` + `step.sleep` + `step.waitForEvent`) · Inngest (event-driven, better DX/observability)
12
13	AI: Workers AI (Llama 3.3 70B FP8 free, Llama 3.1 8B FP8, Llama 4 Scout 17B vision) · AI Gateway (caching + rate-limit + fallback + logging for every LLM call) · Vectorize (embeddings + ANN search)
14
15	## Override conditions (when CF isn't enough)
16
17	\| Need \| Fallback \| Adapter \|
18	\|---\|---\|---\|
19	\| Advanced SQL (RLS, OLAP, partial indexes) \| Neon Postgres via Hyperdrive \| `SqlPort` \|
20	\| Redis primitives at scale (sorted sets, streams) \| Upstash Redis \| `KvPort` \|
21	\| Sub-millisecond global state \| Upstash QStash \| `QueuePort` \|
22	\| Specific provider (OpenAI assistants, Anthropic batch) \| Direct API via AI Gateway \| `AiPort` \|
23	\| Vector + SQL co-located \| Neon pgvector \| `VectorPort` \|
24
25	Adapters live in `libs/core/ports/`. Product code imports port, never vendor SDK directly. See `rules/cloudflare-hostable-supervisor.md`.
26
27	## Auth (default Clerk M2M JWT)
28
29	- Clerk — M2M JWT (free, networkless verification), passkeys, OAuth, magic links; Better Auth when Clerk pricing doesn't fit (rare)
30	- Hash API keys at rest. Audit log every sensitive action.
31	- Tenant isolation: every table carries `org_id`, every query filters by it (404 on mismatch, never 403)
32
33	## Data patterns
34
35	D1
36
37	```toml
38	[[d1_databases]]
39	binding = "DB"
40	database_name = "myapp"
41	```
42
43	- `wrangler types` against `compatibility_date` + bindings (preferred over hand-maintained Env interface)
44	- Drizzle v1 RQBv2 + Zod for query + validation; batch via `db.batch([...])` (no transactions in D1)
45	- Sessions API: `db.withSession(bookmark)` · Time Travel: `wrangler d1 time-travel restore`
46
47	R2: per-extension content-type on upload · lifecycle Standard→IA after 30d · event notifications → Queues at 5000 msg/sec for thumbnailing/indexing · versioning for asset rollback
48
49	Durable Objects: one DO per stateful entity · SQLite-backed, 10GB per DO · direct stub `env.MY_DO.getByName(name)` · alarm misfires → idempotent handler
50
51	## Reliability
52
53	- Workers CPU 10ms free / 50ms paid default (configurable 5min); wall time 30s paid
54	- `ctx.waitUntil()` for async post-response work; `ctx.passThroughOnException()` for graceful degradation
55	- WebSocket + JSRPC payload up to 32 MiB
56
57	## Cost discipline
58
59	- Workers free tier: 100k req/day; Workers Paid: $5/mo (10M req + 30M CPU-ms) + $0.30/M extra req + $0.02/M extra CPU-ms
60	- D1 on Workers Paid: 5GB + 25B rows-read + 50M rows-written/mo; then $0.75/GB-mo + $0.001/M rows-read + $1/M rows-written; no egress; read replication included (verified 2026-06-09)
61	- R2: 10GB free, $0.015/GB-mo, $0/egress · Workers AI Llama 3.3 70B FP8 FREE · AI Gateway free
62	- Solo SaaS <$100k/mo MRR stays 10-100× cheaper than AWS-equivalent on CF
63
64	## Default config (`wrangler.jsonc`)
65
66	```jsonc
67	{
68	"name": "myapp",
69	"main": "src/worker/index.ts",
70	"compatibility_date": "2026-04-15",
71	"compatibility_flags": ["nodejs_compat"],
72	"observability": { "enabled": true },
73	"secrets_r

People who liked this also viewed

6 picks

Type

05-architecture-and-stack

18stars4forks

View on GitHub

How to install 05-architecture-and-stack?

heymegabyte/claude-skills/05-architecture-and-stack

$npx -y skills add heymegabyte/claude-skills --skill 05-architecture-and-stack

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# 05 — Architecture and Stack
2
3	Default stack: `_kernel/standards.md#stack`. Override conditions below.
4
5	## Cloudflare-first decision tree
6
7	Compute: Workers (default, every HTTP/cron/queue) · Pages (static-only marketing, rare) · Containers (non-JS runtimes: Playwright headful, ffmpeg, Python ML, build orchestration) · Sandbox SDK (generated/risky code before live promotion)
8
9	State: D1 (default relational, ≤10GB/db, Sessions API read-replicas, Time Travel 30-day PIT) · KV (eventually-consistent, cache/sessions/feature-flags) · R2 (object storage, lifecycle Standard→IA after 30d) · Durable Objects (coordination + strongly-consistent SQLite storage since Apr 2025, chat rooms/builder sessions/rate-limiting) · Hyperdrive (front external Postgres/MySQL) · Vectorize (semantic search/RAG, 5M dim/index, topK 100, 10 metadata indexes)
10
11	Async: Queues (best-effort, 5000 msg/sec, R2 event notifications) · Workflows v2 (deterministic, 50K concurrent, 300 creates/sec, 2M queued/workflow, `step.do` + `step.sleep` + `step.waitForEvent`) · Inngest (event-driven, better DX/observability)
12
13	AI: Workers AI (Llama 3.3 70B FP8 free, Llama 3.1 8B FP8, Llama 4 Scout 17B vision) · AI Gateway (caching + rate-limit + fallback + logging for every LLM call) · Vectorize (embeddings + ANN search)
14
15	## Override conditions (when CF isn't enough)
16
17	\| Need \| Fallback \| Adapter \|
18	\|---\|---\|---\|
19	\| Advanced SQL (RLS, OLAP, partial indexes) \| Neon Postgres via Hyperdrive \| `SqlPort` \|
20	\| Redis primitives at scale (sorted sets, streams) \| Upstash Redis \| `KvPort` \|
21	\| Sub-millisecond global state \| Upstash QStash \| `QueuePort` \|
22	\| Specific provider (OpenAI assistants, Anthropic batch) \| Direct API via AI Gateway \| `AiPort` \|
23	\| Vector + SQL co-located \| Neon pgvector \| `VectorPort` \|
24
25	Adapters live in `libs/core/ports/`. Product code imports port, never vendor SDK directly. See `rules/cloudflare-hostable-supervisor.md`.
26
27	## Auth (default Clerk M2M JWT)
28
29	- Clerk — M2M JWT (free, networkless verification), passkeys, OAuth, magic links; Better Auth when Clerk pricing doesn't fit (rare)
30	- Hash API keys at rest. Audit log every sensitive action.
31	- Tenant isolation: every table carries `org_id`, every query filters by it (404 on mismatch, never 403)
32
33	## Data patterns
34
35	D1
36
37	```toml
38	[[d1_databases]]
39	binding = "DB"
40	database_name = "myapp"
41	```
42
43	- `wrangler types` against `compatibility_date` + bindings (preferred over hand-maintained Env interface)
44	- Drizzle v1 RQBv2 + Zod for query + validation; batch via `db.batch([...])` (no transactions in D1)
45	- Sessions API: `db.withSession(bookmark)` · Time Travel: `wrangler d1 time-travel restore`
46
47	R2: per-extension content-type on upload · lifecycle Standard→IA after 30d · event notifications → Queues at 5000 msg/sec for thumbnailing/indexing · versioning for asset rollback
48
49	Durable Objects: one DO per stateful entity · SQLite-backed, 10GB per DO · direct stub `env.MY_DO.getByName(name)` · alarm misfires → idempotent handler
50
51	## Reliability
52
53	- Workers CPU 10ms free / 50ms paid default (configurable 5min); wall time 30s paid
54	- `ctx.waitUntil()` for async post-response work; `ctx.passThroughOnException()` for graceful degradation
55	- WebSocket + JSRPC payload up to 32 MiB
56
57	## Cost discipline
58
59	- Workers free tier: 100k req/day; Workers Paid: $5/mo (10M req + 30M CPU-ms) + $0.30/M extra req + $0.02/M extra CPU-ms
60	- D1 on Workers Paid: 5GB + 25B rows-read + 50M rows-written/mo; then $0.75/GB-mo + $0.001/M rows-read + $1/M rows-written; no egress; read replication included (verified 2026-06-09)
61	- R2: 10GB free, $0.015/GB-mo, $0/egress · Workers AI Llama 3.3 70B FP8 FREE · AI Gateway free
62	- Solo SaaS <$100k/mo MRR stays 10-100× cheaper than AWS-equivalent on CF
63
64	## Default config (`wrangler.jsonc`)
65
66	```jsonc
67	{
68	"name": "myapp",
69	"main": "src/worker/index.ts",
70	"compatibility_date": "2026-04-15",
71	"compatibility_flags": ["nodejs_compat"],
72	"observability": { "enabled": true },
73	"secrets_r

People who liked this also viewed

6 picks

Type