this repo has no description
clankers: improve doc
+82
-7
+82
-7
AGENTS.md
+82
-7
AGENTS.md
···
1
1
# final project csc 317
2
2
3
-
- decentralized code competition platform on atproto
4
-
- stack uses vite + tanstack start + solidjs + tailwindcss
5
-
- deployed on cloudflare workers by CD pipeline
6
-
- database is a cloudflare d1 interacted via prisma
7
-
- the oauth-client-metadata.json is created by scripts/generate-metadata.ts
8
-
- this project uses `pnpm` for dependencies management
3
+
decentralized code competition platform on atproto
4
+
9
5
- keep code well organized
10
-
- use server function as much as possible
11
6
- always use pnpm run scripts, not direct binary invocations
7
+
8
+
9
+
## commands
10
+
11
+
All commands run from `app/` via `pnpm run <name>` (workspace-wide: `pnpm
12
+
--filter app …`).
13
+
14
+
- `dev` — Vite dev server on `127.0.0.1:5173`. Bound to `127.0.0.1`, not
15
+
`localhost`, because atproto OAuth (RFC 8252) rejects the `localhost`
16
+
hostname.
17
+
- `build` / `preview` — production build / local preview of the built worker
18
+
- `test` — `vitest run` (single file: `pnpm test path/to/file.test.ts`)
19
+
- `check` — `tsc -p tsconfig.json`, no emit
20
+
- `lint` / `lint:check` — eslint with/without `--fix`
21
+
- `format` / `format:check` — prettier write/check
22
+
- `db:generate` — regenerate Prisma client into `src/generated/prisma`
23
+
- `wrangler:generate` — regenerate `worker-configuration.d.ts` from
24
+
`wrangler.toml` + `.env.example`
25
+
- `lexicon:generate` — `lex-cli generate && lex-cli export` (types into
26
+
`src/generated/lexicons/`, schemas exported to `public/lexicons/`)
27
+
- `postinstall` — runs all four generators in order. Re-run after editing
28
+
`prisma/schema.prisma`, `lexicons/**`, `wrangler.toml`, or `.env.example`.
29
+
30
+
31
+
## architecture
32
+
33
+
- Single Cloudflare Worker entry: `@tanstack/solid-start/server-entry` (set in
34
+
`wrangler.toml`). Vite plugin order: Cloudflare → Tailwind → TanStack Start →
35
+
Solid (SSR on).
36
+
- Routing is file-based under `src/routes/`. `src/routeTree.gen.ts` is generated
37
+
by `@tanstack/router-plugin` — never hand-edit. Root shell in
38
+
`src/routes/__root.tsx` wires `AuthProvider` → `ProfileProvider` → `Header` →
39
+
`<Outlet/>`.
40
+
- Server functions are the primary RPC mechanism — defined with `createServerFn`
41
+
from `@tanstack/solid-start`. Server-only modules live in `src/server/` and
42
+
use the `.server.ts` suffix; they bind to `cloudflare:workers` env.
43
+
- Persistence: Prisma client (`runtime = "workerd"`, sqlite provider) wrapped
44
+
with `@prisma/adapter-d1` against the `DB` D1 binding. Schema migrations are
45
+
**Wrangler D1 SQL files** in `migrations/` — not Prisma migrations. CI applies
46
+
them via `cloudflare/wrangler-action`.
47
+
- Auth: atproto OAuth via `@atcute/oauth-node-client`. Client metadata is built
48
+
at runtime (`src/lib/oauth-metadata.ts`) and also baked into
49
+
`public/oauth-client-metadata.json` by `scripts/generate-metadata.ts`. JWKS
50
+
served at `/oauth/jwks`. In dev mode the client runs without a keyset;
51
+
production loads `PRIVATE_KEY_JWK` from env.
52
+
- Lexicons: source TS specs under `lexicons/at.compiles.alpha/` (e.g. `problem`,
53
+
`submission`); generator emits typed clients into `src/generated/lexicons/`
54
+
and exports JSON to `public/lexicons/`.
55
+
- Sessions: encrypted cookie via `useSession` from
56
+
`@tanstack/solid-start/server` (`src/lib/session.ts`), keyed by
57
+
`SESSION_SECRET`. Only stores an opaque token; user lookup goes through
58
+
`prisma.session`.
59
+
60
+
61
+
## path aliases (tsconfig)
62
+
63
+
- `~/*` → `src/*`
64
+
- `$/*` → `src/lib/*`
65
+
- `@/*` → `src/lib/components/*`
66
+
- `#/*` → `src/generated/lexicons/*`
67
+
68
+
69
+
## generated — do not hand-edit
70
+
71
+
- `src/generated/prisma/`
72
+
- `src/generated/lexicons/`
73
+
- `src/routeTree.gen.ts`
74
+
- `worker-configuration.d.ts`
75
+
- `public/oauth-client-metadata.json`
76
+
- `public/lexicons/`
77
+
78
+
79
+
## deployment
80
+
81
+
GitHub Actions (`.github/workflows/frontend.yml`) gates on `check` +
82
+
`lint:check` + `format:check` + `d1 migrations apply --local`. On `main`, it
83
+
builds, applies migrations to remote D1, and deploys via `wrangler-action`.
84
+
85
+
Workspace is a single-package pnpm workspace (`app`);
86
+
reproducible dev env via Nix flake (`nodejs_24`, corepack, `prisma-engines_7`).
12
87
13
88
14
89
<!-- intent-skills:start -->