Architecture
prompy/├── web/ Next.js 16 app (App Router, Server Actions, Tailwind v4)├── docs/ This site — Astro + Starlight└── supabase/ SQL migrations (schema, row-level security, RPC functions)| Concern | Choice |
|---|---|
| App | Next.js on Vercel (Fluid Compute, Node.js runtime) |
| Database & auth | Supabase Postgres + Supabase Auth (email + Google) — free tier |
| Images | imgbb API, called server-side from /api/upload |
| MCP | mcp-handler at /api/mcp, Streamable HTTP |
| AI news | /api/ai-news, aggregated from public feeds and cached for 15 minutes |
| Theming | next-themes, light / dark / system |
| Docs | Astro Starlight |
Data model
Section titled “Data model”profiles— one per user, created by a trigger on sign-up.prompts—owner_id, optionalworkspace_id,tags text[],visibility.workspaces,workspace_members— rolesowner,editor,viewer.workflows,workflow_steps— multi-step workflow templates (migration 0018). A workflow is shared like a prompt (visibility, optionalworkspace_id;can_read_workflowmirrorscan_read_prompt). Steps follow their workflow: workspace owners and editors edit, viewers read.save_workflow_steps(wid, steps)is asecurity invokerfunction that replaces a workflow’s steps in one transaction. Admins (is_admin()) can read every workflow and its steps, unpublish public ones and delete any (migration 0019).learning_resources— the Learning Hub at/courses(migration 0020). Everyone, signed out included, reads rows withis_published; admins (is_admin()) read drafts and are the only ones who can insert, update or delete. A trigger normalises topics (lowercase, unique, at most 8), keepsyoutube_idonly on videos and fixescreated_by.urlis unique.design_templates— Design Templates, curated at/admin/templates(migration 0024). Same read rule aslearning_resources: published rows for everyone, drafts for admins, writes for admins only. Column grants keepcopy_countout of reach of the app; onlyincrement_template_copy(id)(security definer, callable by anyone, published rows only) adds one. A trigger normalises style tags (lowercase, unique, at most 6) and the palette (lowercase#rrggbb, at most 8), checks thatscreenshotsonly hasdesktop,mobileanddarkkeys with https or/templates/links, fixescreated_by, and leavesupdated_atalone when only the copy count changes.slugis unique.likes,comments— likes and new comments are limited to public prompts; comment reads also require access to the referenced prompt.api_tokens— SHA-256 hashes of MCP tokens.activity_logs— append-only admin, prompt and authentication events; readable only by admins.backup_runs,app_settings— Google Drive backup history and operational settings such as the backup folder and retention (migration 0021). Only super admins can read them, and only the server’s backup job writes them, through the service role.prompt_feed— asecurity_invokerview adding like/comment counts.related_prompts(source_id, max_results)— asecurity invokerfunction that ranks prompts by shared tags, then title/note keywords (built-in full-text search), then likes and recency. It powers the related prompts on each prompt page.
Access control
Section titled “Access control”All rules live in Postgres row-level security, so the browser-facing anon key is safe to ship:
- A prompt is readable if it’s public, you own it, or you’re a member of its workspace.
- Writes to a workspace prompt need the
owneroreditorrole. /api/ai-newsreads no user data, so it skips the auth proxy and needs no key.- MCP calls go through
security definerfunctions (mcp_search_prompts,mcp_get_prompt,mcp_create_prompt,mcp_list_tags) that resolve the token to a user first. No service-role key is needed anywhere.
AI news aggregator
Section titled “AI news aggregator”GET /api/ai-news merges the latest AI posts into one list. It powers the in-app news feed and is public.
| Source | Where it comes from |
|---|---|
| OpenAI | https://openai.com/news/rss.xml |
| Hugging Face | https://huggingface.co/blog/feed.xml |
| Anthropic | Hacker News stories linking to anthropic.com or claude.com (Anthropic publishes no RSS feed) |
| Groq | Hacker News stories linking to groq.com (Groq publishes no RSS feed) |
| Community | Hacker News stories with 20+ points mentioning LLM, OpenAI, Anthropic, Claude or Groq in the title |
How it behaves:
- Each upstream request and the merged result are cached for 15 minutes, so traffic to Prompy never reaches the sources directly.
- A source that times out (8 s) or returns something that isn’t a feed is skipped and reported as
ok: false. The other sources still load. The route returns502only when every source fails. - Items are de-duplicated by URL. When a vendor post is also on Hacker News, the vendor copy is kept.
- Feed text is untrusted. Summaries are converted to plain text and cut to 280 characters, and only
https:links and images are kept. - Admins can turn the whole feature off with the
ai_newsflag in/admin/flags. The route then returns404.
Article previews
Section titled “Article previews”Feeds rarely include images, and Hacker News has no summaries. So for the items on the page being served, and never the whole feed, Prompy reads each article’s own preview tags (og:image, og:description, twitter:*, meta description). The preview step:
- caches each article’s preview for a day, so a page triggers at most
limitfetches and repeat views trigger none - waits 3 seconds at most per page; slower previews finish in the background and show up on the next request
- only fetches
https:URLs on the default port whose hostname resolves to public addresses. IP literals,localhost, private, loopback and link-local ranges are refused, and each redirect is re-checked. - reads at most 256 KB of
text/htmlper article, with a 4 s timeout, and keeps descriptions as plain text and images ashttps:URLs only - shows Hacker News points and comments in a separate
metafield
Some sites, OpenAI among them, block automated requests. Their cards keep the feed’s own text and show the source instead of an image.
Query parameters
Section titled “Query parameters”| Param | Default | Allowed |
|---|---|---|
page |
1 |
1 or more |
limit |
10 |
1 to 30 |
source |
all |
all, anthropic, openai, groq, huggingface, community |
Response
Section titled “Response”{ "items": [ { "id": "3f2a9c1b7e5d4a60", "title": "Introducing …", "summary": "Plain-text summary, at most 280 characters.", "url": "https://openai.com/index/…", "source": "openai", "publishedAt": "2026-11-13T15:00:00.000Z", "tags": ["product"], "imageUrl": "https://…/cover.png", "meta": "123 points · 45 comments on Hacker News" } ], "page": 1, "limit": 10, "total": 187, "hasMore": true, "sources": [{ "source": "openai", "ok": true, "count": 60 }]}imageUrl and meta are included only when there is one. Errors are { "error": "…" } with status 400 (bad parameters), 404 (feature off), 429 (more than 60 requests a minute from one IP) or 502 (every source down).
Feature flags
Section titled “Feature flags”Admins switch features on and off at Admin → Flags (/admin/flags). A change applies on the next page load, with no deploy, and is recorded in Admin → Logs as feature_flag.updated.
The list of flags lives in code (web/lib/flags.ts), with a label, a description, a group and a default for each. The feature_flags table only stores the current value. If a flag has no row, or the table can’t be read, the default applies; switching such a flag in the admin page creates its row.
| Flag | Default | What it controls |
|---|---|---|
public_feed |
on | The Explore feed (/explore) and its nav links. Off shows a paused notice. |
courses_hub |
off | The Learning Hub (/courses) and its nav link. Off returns 404. |
ai_news |
on | AI News & Blog (/blog), GET /api/ai-news and the landing page’s Latest in AI row. |
app_bots |
on | The AI chat section on the landing page. |
pip_assistant |
on | The Ask Pip chat. Off hides it and POST /api/chat returns 404. |
ai_prompt_enhancer |
off | Enhance prompt in the editor. |
ai_auto_tags |
off | Suggest tags in the editor. |
image_search |
on | Find an image in the editor (also needs an image provider key). |
backups |
off | The scheduled Google Drive backup. Back up now works either way. |
To add a flag: add an entry to FLAGS in web/lib/flags.ts, seed its row in a new migration, and read it on the server with isEnabled("your_flag").