Webapp Overview

Relevant source files

The following files were used as context for generating this wiki page:

• packages/webapp/ROUTING_IMPLEMENTATION.md
• packages/webapp/BUILDING.md
• packages/webapp/SETUP_COMPLETE.md
• packages/webapp/E2E_SETUP_COMPLETE.md
• packages/webapp/src/app/blog/format-specifications-guide/page.tsx
• packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx
• packages/registry/src/services/seo-data.ts
• packages/webapp/src/app/blog/agents-md-deep-dive/page.tsx
• packages/webapp/src/app/blog/openskills-cross-ide-compatibility/page.tsx

The prpm webapp is a Next.js 14 application that serves as the primary user interface for the Prompt Package Manager (PRPM) ecosystem. It provides marketing content, user authentication, package discovery, and detailed technical documentation through its blog. The application is built with TypeScript and styled with Tailwind CSS.

A key architectural feature is its dual-domain structure, which separates public-facing marketing content from the authenticated application experience. This provides a clear separation of concerns, enhances security, and improves performance by allowing different caching strategies for each domain.

Sources: packages/webapp/SETUP_COMPLETE.md, packages/webapp/ROUTING_IMPLEMENTATION.md

Architecture and Routing

The webapp employs a dual-domain architecture to segregate marketing pages from the core application.

• Main Domain (prpm.dev): Hosts the landing page, authentication flows (login/signup), and the author invite claim process.
• App Subdomain (app.prpm.dev): Hosts the authenticated application experience, including the user dashboard, package search, and author directory.

This separation is managed by middleware and Next.js route groups.

Sources: packages/webapp/ROUTING_IMPLEMENTATION.md:5-9, packages/webapp/ROUTING_IMPLEMENTATION.md:47-56

Dual-Domain Routing Logic

The following diagram illustrates the routing logic enforced by the middleware for production environments. In local development, all routes are accessible on localhost without redirects to simplify the development workflow.

File Structure and Route Groups

The project uses Next.js route groups to organize files without affecting the URL structure. Routes for the app subdomain are placed within the (app) directory.

• src/app/(app)/: Contains layouts and pages for the app.prpm.dev subdomain. The (app) folder does not add /app to the URL.
• src/app/: Contains pages for the main prpm.dev domain, such as the landing page (page.tsx), login, and signup.

Sources: packages/webapp/ROUTING_IMPLEMENTATION.md:13-21, packages/webapp/ROUTING_IMPLEMENTATION.md:104-107

URL Structure

The table below summarizes the designated routes for each domain.

Domain	Route	Purpose
prpm.dev	/	Landing page with features and CLI examples.
prpm.dev	/login, /signup	User authentication and registration.
prpm.dev	/claim, /claim/[token]	Author invite claim flow.
prpm.dev	/blog/*	Technical articles and guides.
app.prpm.dev	/dashboard	User dashboard and package management.
app.prpm.dev	/search	Package search and discovery.
app.prpm.dev	/authors	Author directory and profiles.
Shared	/auth/callback	Handles OAuth callbacks from services like GitHub.

Sources: packages/webapp/ROUTING_IMPLEMENTATION.md:58-80

Key Features

The webapp is designed as a comprehensive platform for both discovering and learning about AI coding tools.

Sources: packages/webapp/src/app/blog/prpm-complete-feature-guide/page.tsx:28-31

Author Invite Claim Flow

A primary feature is the author invite claim flow, which allows authors to claim their profiles on PRPM.

1. An author receives an invite token.
2. They enter the token on the /claim page.
3. The app validates the token via a GET /api/v1/invites/:token call to the registry.
4. Upon successful validation, the user authenticates via GitHub OAuth.
5. The app receives a JWT from the registry and completes the claim process.

Sources: packages/webapp/SETUP_COMPLETE.md:14-23, packages/webapp/SETUP_COMPLETE.md:83-93

The sequence diagram below details the interaction between the user, webapp, and registry during the claim process.

Content and Documentation

A significant portion of the webapp is dedicated to providing in-depth technical articles and guides via its blog. This content serves to educate users on the various AI IDE prompt formats and best practices. The webapp is the central hub for "distributable intelligence" for AI assistants.

Sources: packages/webapp/src/app/blog/distributable-intelligence/page.tsx:28-31, packages/webapp/src/app/blog/format-specifications-guide/page.tsx:38-45

The webapp documents and supports conversion between numerous AI IDE formats, including:

Format	File Location	Frontmatter	Key Features
Cursor	.cursor/rules	Required	4 rule types, MDC format
Claude Code	.claude/{agents,skills,commands}/	Required	Tool restrictions, model selection
Continue	.continue/rules/*.md	Required	Globs, regex matching
Windsurf	.windsurf/rules	None	Plain markdown, 12k char limit
GitHub Copilot	.github/copilot-instructions.md	Optional	Two-tier system, path-specific rules
Kiro Steering	.kiro/steering/*.md	Optional	Inclusion modes, domain organization
Kiro Hooks	.kiro/hooks/*.json	N/A (JSON)	Event-driven file automation
agents.md	agents.md	None	Open standard, plain markdown

Sources: packages/webapp/src/app/blog/format-specifications-guide/page.tsx:103-181

The blog also covers advanced concepts like tool composition, demonstrating how tools like OpenSkills and Ruler can be combined to create universally compatible AGENTS.md files.

Sources: packages/webapp/src/app/blog/openskills-cross-ide-compatibility/page.tsx:43-57

Build and Deployment

The webapp uses Next.js with Static Site Generation (SSG) to pre-render all package, collection, and blog pages at build time. This ensures fast load times and optimal SEO.

Sources: packages/webapp/BUILDING.md:5-8

Build Process

The build process fetches all package and collection data from the registry and generates static HTML pages for each one.

The build generates a full static export in the ./out directory, including HTML pages for all packages and collections, sitemap.xml, robots.txt, and Next.js assets.

Sources: packages/webapp/BUILDING.md:55-70

Incremental Static Regeneration (ISR) via Webhooks

To keep the static site updated without frequent full rebuilds, the registry uses an incremental update mechanism. When a package is updated, the SeoDataService triggers a targeted update.

1. Fetches the single updated package's data.
2. Downloads the main packages.json from S3, updates or adds the package, and re-uploads it.
3. Fetches a template HTML page from the live webapp.
4. Replaces the data in the template with the new package data.
5. Uploads the newly generated HTML file to the webapp's S3 bucket.
6. Invalidates the CloudFront cache for the specific page.

This process ensures that individual package pages can be updated in near real-time.

Sources: packages/registry/src/services/seo-data.ts:46-70, packages/registry/src/services/seo-data.ts:153-180

Testing

The webapp has a comprehensive end-to-end (E2E) testing infrastructure using Playwright, with 34 test cases covering the home page, author leaderboard, and invite claim flow.

Sources: packages/webapp/E2E_SETUP_COMPLETE.md:5-13

Test Modes

Three distinct modes are available for running tests, providing flexibility for different environments.

Mode	Command	Description
Mock API	npm run test:e2e	Default mode. Uses Playwright route interception. Fast, reliable, and has no external dependencies. Ideal for local development.
Real API	npm run test:e2e:real	Tests against a running registry backend with real data.
Docker	npm run test:docker	Runs a complete, isolated stack (PostgreSQL, Redis, MinIO, Registry, Webapp) via Docker Compose. Recommended for CI.

Sources: packages/webapp/E2E_SETUP_COMPLETE.md:21-41

Conclusion

The PRPM webapp is a critical component of the ecosystem, serving as the primary interface for users. Its dual-domain architecture effectively separates marketing from application logic, while its static generation build process ensures high performance and SEO. The integrated blog establishes it as a key resource for learning about AI development standards, and a robust E2E testing suite ensures reliability across its core user flows.