Add submission & review system (#8)

* Add submission & review system

- Wire up the ship button in projects page to call submit API
- Add /review dashboard for admins to review pending submissions
- Implement buff system with live M calculation and payout preview
- Add review API endpoint with approve/reject actions
- Post review results to Slack #raspapi-logs
- Update .env.example with ADMIN_IDS, SLACK_BOT_TOKEN, SLACK_LOGS_CHANNEL

https://claude.ai/code/session_019nt7obPSBSVJKfnf5RDA6U

* fix: apply biome formatting

https://claude.ai/code/session_019nt7obPSBSVJKfnf5RDA6U

* Hedging my ledger

* DM approval/rejection status, better logging

* Format, buff it up

* Drop 5-7 explicit hour req

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: sadeshmukh

.env.example

@@ -12,4 +12,12 @@ PUBLIC_BASE_URL=http://localhost:4321
 
 # readonly is fine
 AIRTABLE_API_KEY=pat-
-AIRTABLE_BASE_ID=app-
+AIRTABLE_BASE_ID=app-
+AIRTABLE_SUBMISSIONS_TABLE_ID=tbl-
+
+# comma-separated Slack IDs for admin/reviewer access
+ADMIN_IDS=U123,U456
+
+# review
+SLACK_BOT_TOKEN=xoxb-
+SLACK_LOGS_CHANNEL=C0123456789

bun.lockb

@@ -0,0 +1,13 @@
+display_information:
+  name: RaspAPI
+
+features:
+  bot_user:
+    display_name: RaspAPI
+    always_online: false
+
+oauth_config:
+  scopes:
+    bot:
+      - chat:write
+      - im:write

manifest.yml

@@ -16,6 +16,7 @@
     "@astrojs/node": "^9.5.1",
     "@tailwindcss/vite": "^4.1.18",
     "astro": "^5.16.8",
+    "slack.ts": "0.0.15",
     "tailwindcss": "^4.1.18",
     "three": "^0.182.0",
     "typescript": "^5.9.3"

package.json

@@ -20,5 +20,6 @@ Before submitting your project, make sure you meet the following requirements:
 - Your API should include docs at `/docs`. These can be handwritten or auto-generated (Swagger, Redoc, Scalar, etc.), but should clearly explain your endpoints and give an example of a valid request for each.
 - Your API should be usable by anyone. If it requires auth or API keys, make sure there's a way for people to easily get access, such as with a demo key on your docs.
 - Your code should be in a public git repo with a (hand-written, please) README explaining what it is.
-- You should have around 5–7 hours tracked on Hackatime.
 - Make something cool and have fun!
+
+Reviewers award a multiplier based on what your API implements - see the [Buffs & Multipliers](/guides/buffs) guide for details on how payouts are calculated.

src/content/guides/about.md

@@ -0,0 +1,73 @@
+---
+title: Buffs & Multipliers
+description: How the review multiplier system works
+order: 1
+---
+
+*Note: these values are subject to change as we iterate.*
+
+When your submission is reviewed, a reviewer assigns a **multiplier** based on what your API implements. The multiplier directly scales your payout:
+
+> **Payout = hours × 4 × multiplier**
+
+So if you logged 6 hours and your multiplier is 1.25, you'd receive 30 raspberries.
+
+## How the Multiplier Is Built
+
+The multiplier starts at **1.0** and is built in two stages:
+
+1. **Flat bonuses** are added together (capped at 1.5 total)
+2. **Multiplier buffs** are applied on top of the capped value
+
+---
+
+## Flat Bonuses
+
+These are additive. Reviewers check your project for each one and add the bonus if it qualifies.
+
+| Buff | Bonus |
+|------|-------|
+| Authorization (JWT, user tokens, API keys) | +0.15 |
+| Persistence (database, file storage) | +0.10 |
+| External API integration (non-trivial) | +0.10 |
+| Rate limiting / abuse prevention | +0.10 |
+| Pagination | +0.05 |
+| Proper error handling & input validation | +0.05 |
+| Additional endpoints beyond the minimum, up to 4 | +0.03 each |
+
+The sum of all flat bonuses is **capped at 1.5** before multiplier buffs are applied. If your bonuses add up to 1.6, they'll be treated as 1.5.
+
+---
+
+## Multiplier Buffs
+
+These are applied after the flat bonus cap and stack multiplicatively.
+
+| Buff | Multiplier |
+|------|------------|
+| Cool project | ×1.3 |
+| Exceptional code quality / architecture | ×1.2 |
+
+---
+
+## Example
+
+Say your API has:
+
+- Auth (+0.15)
+- A database (+0.10)
+- Rate limiting (+0.10)
+- Solid error handling (+0.05)
+- 2 extra endpoints (+0.06)
+
+That's **1.0 + 0.46 = 1.46**. Below the 1.5 cap, so no clipping.
+
+If the reviewer also thinks it's a cool project (×1.3):
+
+**1.46 × 1.3 = 1.898**
+
+With 6 hours logged: **6 × 4 × 1.898 = ~46 raspberries**.
+
+---
+
+Buffs are awarded at reviewer discretion. Please do not ask for specific buffs in your submission notes, but do make sure to highlight any features you implemented that you think are cool and deserve recognition!

src/content/guides/buffs.md

@@ -130,8 +130,8 @@ However, real APIs usually have multiple endpoints and different request types l
 
 The parsed HTTP request stored in struct mg_http_message contains two important fields:
 
-- `hm->uri` — the request path (for example /api/hello)
-- `hm->method` — the HTTP method (GET, POST, etc.)
+- `hm->uri` - the request path (for example /api/hello)
+- `hm->method` - the HTTP method (GET, POST, etc.)
 
 You can use these to create multiple endpoints. You need at least 3 GET endpoints and 1 POST endpoint to submit your project.
 

src/content/guides/building/c-mongoose.md

@@ -14,7 +14,7 @@ const guides = await getCollection("guides");
 const grouped = guides.reduce(
 	(acc, guide) => {
 		const parts = guide.id.split("/");
-		const category = parts.length > 1 ? parts[0] : "general";
+		const category = parts.length > 1 ? parts[0] : "about";
 		if (!acc[category]) acc[category] = [];
 		acc[category].push(guide);
 		return acc;

src/layouts/DocsLayout.astro

@@ -331,3 +331,164 @@ export async function createSubmission(
 		payout_transaction_id: r.fields.payout_transaction?.[0] ?? undefined,
 	};
 }
+
+export interface SubmissionWithProject extends SubmissionRecord {
+	project_name: string;
+	project_description: string;
+	project_url?: string;
+	repo_url?: string;
+	image_url?: string;
+	user_slack_id: string;
+	created_at: string;
+}
+
+export async function getPendingSubmissions(): Promise<
+	SubmissionWithProject[]
+> {
+	const submissions: SubmissionWithProject[] = [];
+	const filter = encodeURIComponent(`{review_status}="submitted"`);
+	let offset: string | undefined;
+
+	do {
+		const url = new URL(
+			`${BASE()}/submissions?filterByFormula=${filter}&sort%5B0%5D%5Bfield%5D=id&sort%5B0%5D%5Bdirection%5D=asc`,
+		);
+		if (offset) url.searchParams.set("offset", offset);
+		const res = await fetch(url.toString(), { headers: HEADERS() });
+		if (!res.ok) break;
+		const data = await res.json();
+		for (const r of data.records ?? []) {
+			const projectId = r.fields.project?.[0];
+			let project: ProjectRecord | null = null;
+			if (projectId) {
+				project = await getProjectById(projectId);
+			}
+			submissions.push({
+				id: r.id,
+				project_id: projectId ?? "",
+				hours_at_submission: r.fields.hours_at_submission ?? 0,
+				review_status: r.fields.review_status ?? "submitted",
+				reviewer_notes: r.fields.reviewer_notes ?? "",
+				multiplier: r.fields.multiplier ?? 1,
+				payout: r.fields.payout ?? 0,
+				payout_transaction_id: r.fields.payout_transaction?.[0] ?? undefined,
+				project_name: project?.name ?? "",
+				project_description: project?.description ?? "",
+				project_url: project?.project_url,
+				repo_url: project?.repo_url,
+				image_url: project?.image_url,
+				user_slack_id: project?.user_slack_id ?? "",
+				created_at: r.createdTime ?? "",
+			});
+		}
+		offset = data.offset;
+	} while (offset);
+
+	return submissions;
+}
+
+export async function getSubmissionById(
+	id: string,
+): Promise<SubmissionWithProject | null> {
+	const res = await fetch(`${BASE()}/submissions/${id}`, {
+		headers: HEADERS(),
+	});
+	if (!res.ok) return null;
+	const r = await res.json();
+	const projectId = r.fields.project?.[0];
+	let project: ProjectRecord | null = null;
+	if (projectId) {
+		project = await getProjectById(projectId);
+	}
+	return {
+		id: r.id,
+		project_id: projectId ?? "",
+		hours_at_submission: r.fields.hours_at_submission ?? 0,
+		review_status: r.fields.review_status ?? "submitted",
+		reviewer_notes: r.fields.reviewer_notes ?? "",
+		multiplier: r.fields.multiplier ?? 1,
+		payout: r.fields.payout ?? 0,
+		payout_transaction_id: r.fields.payout_transaction?.[0] ?? undefined,
+		project_name: project?.name ?? "",
+		project_description: project?.description ?? "",
+		project_url: project?.project_url,
+		repo_url: project?.repo_url,
+		image_url: project?.image_url,
+		user_slack_id: project?.user_slack_id ?? "",
+		created_at: r.createdTime ?? "",
+	};
+}
+
+export async function updateSubmissionReview(
+	id: string,
+	data: {
+		review_status: "approved" | "rejected";
+		multiplier: number;
+		reviewer_notes: string;
+		buffs: string;
+	},
+): Promise<boolean> {
+	const res = await fetch(`${BASE()}/submissions/${id}`, {
+		method: "PATCH",
+		headers: HEADERS(),
+		body: JSON.stringify({
+			fields: {
+				review_status: data.review_status,
+				multiplier: data.multiplier,
+				reviewer_notes: data.reviewer_notes,
+				buffs: data.buffs,
+			},
+		}),
+	});
+	return res.ok;
+}
+
+export async function updateProjectApprovedHours(
+	id: string,
+	approved_hours: number,
+): Promise<boolean> {
+	const res = await fetch(`${BASE()}/projects/${id}`, {
+		method: "PATCH",
+		headers: HEADERS(),
+		body: JSON.stringify({ fields: { approved_hours } }),
+	});
+	return res.ok;
+}
+
+export async function createLedgerEntry(
+	userAirtableId: string,
+	submissionId: string,
+	reason: string,
+): Promise<string | null> {
+	const res = await fetch(`${BASE()}/ledger`, {
+		method: "POST",
+		headers: HEADERS(),
+		body: JSON.stringify({
+			records: [
+				{
+					fields: {
+						user: [userAirtableId],
+						type: "project_payout",
+						reason,
+						payout_submission: [submissionId],
+					},
+				},
+			],
+		}),
+	});
+	if (!res.ok) return null;
+	const data = await res.json();
+	return data.records?.[0]?.id ?? null;
+}
+
+export async function linkSubmissionPayoutTransaction(
+	submissionId: string,
+	ledgerRecordId: string,
+): Promise<boolean> {
+	const res = await fetch(`${BASE()}/submissions/${submissionId}`, {
+		method: "PATCH",
+		headers: HEADERS(),
+		body: JSON.stringify({ fields: { payout_transaction: [ledgerRecordId] } }),
+	});
+	return res.ok;
+}