Blueprint
Product thesis and MVP scope
Provide React developers with a framework and cloud platform that drastically reduces the time and complexity of building and scaling full-stack applications on AWS, while offering a clear path to enterprise reliability and support.
Target user
Full-stack developers and platform engineers in AWS-centric organizations building customer-facing web applications with React.
MVP scope
- File-system based routing with support for pages and API routes.
- React Server Components with streaming and suspense.
- Static generation (SSG) and server-side rendering (SSR) modes.
- Zero-config deployment to AWS Lambda@Edge and CloudFront via CLI.
- Automatic code splitting and optimized production builds.
- Built-in environment variable management with `.env` support.
- Basic analytics dashboard showing request count and latency.
- Developer documentation and a ‘create-my-app’ scaffolding CLI.
System
Entities, flows, and modules
Entities
Project
id, name, config (route types, plugins), environmentVariables, deploymentTarget, lastDeployment — Represents a developer's project; central entity that ties code to deployments and analytics.
Deployment
id, projectId, status, url, logs, createdAt, environment — Represents a deployed version of the project on the hosting platform; tracks build output and live domain.
Page
path, route, getStaticProps, getServerSideProps, component — A page in the file-system routing; could be static or dynamic, rendered on server or client.
User
id, email, orgId, role — Developer account for framework CLI and platform; may be part of an organization.
Flows
Create new project
CLI: `create my-app` — Scaffolds a new Next.js-like project with default configuration and local dev server.
Local development with hot reload
`localhost:3000` — Developer runs `npm run dev` to see live preview of app with RSC, SSR, and file-based routing.
Deploy project
CLI: `deploy` — Builds the project for production and deploys to the hosting platform, returning a live URL.
View deployment analytics
Dashboard: `/projects/[id]/analytics` — Shows request volume, latency, and error rates for the deployed project.
Manage environment variables
Dashboard: `/projects/[id]/settings/env` — Add, edit, or remove environment variables that are injected at build and runtime.
Link local project to platform
CLI: `link` — Connects a local project to an existing platform project for deployments and sync.
Backend modules
Routing Engine
Handles file-system based route resolution, mapping URL paths to page components and server functions. — Core of the framework; must be implemented first to enable basic app structure.
Build System
Compiles and bundles the application, including Rust-based optimizer, code splitting, and static generation. — Required to produce deployable artifacts and optimize for production.
Deployment Service
Manages project builds and deploys to cloud infrastructure (e.g., S3 + CloudFront + Lambda). — Enables the key monetization path of hosting; differentiates from pure framework by providing cloud integration.
Analytics Service
Collects and displays request metrics, using serverless function logs and edge data. — Adds value for paid tiers and observability, a missing piece in the source repo.
CLI
Command-line interface for scaffolding, dev server, and deployment commands. — Developer entry point; must be provided from day one for usability.
Phases
Implementation phases
Phase 1: Foundation - Core Framework
Build a minimal file-system router and server-side rendering engine that can serve React components.
Deliverables
- Basic `pages/` directory routing
- Simple dev server with hot reload
- Production build with code splitting
- CLI with `init` and `dev` commands
Exit criteria
- Can create a new project, run `dev`, navigate between pages, and build a static production bundle.
Phase 2: Cloud Deployment & Hosting MVP
Integrate with AWS Lambda@Edge to enable zero-config deployment from the CLI.
Deliverables
- AWS Lambda wrapper for server components
- CloudFront distribution setup via CLI
- Deployment lifecycle management (build, upload, activate)
- Basic dashboard with project list and deploy button
Exit criteria
- User can run `deploy` and get a live URL serving the application, with ability to view deployments in a web dashboard.
Phase 3: Advanced Framework Features
Add React Server Components, streaming, dynamic routes, and incremental static regeneration.
Deliverables
- Server Components support with streaming
- Dynamic route segments (e.g., [id])
- ISR with SWR caching on edge
- API routes (pages/api)
- Environment variable injection
Exit criteria
- Developers can use RSC, dynamic routes, and API routes; app deploys with automatic ISR.
Phase 4: Enterprise Features & Observability
Add team management, SSO, analytics, and performance monitoring.
Deliverables
- Organization and team accounts
- Role-based access (admin, developer)
- Real-time request analytics dashboard
- Error tracking and alerting
- SSO integration with SAML/OIDC
Exit criteria
- Enterprise teams can manage users, view performance data, and get alerts; platform meets basic enterprise security requirements.
Phase 5: Scale & Ecosystem
Optimize for large-scale adoption, add plugins, and support for custom cloud providers.
Deliverables
- Plugin system for custom build steps
- Support for Azure and GCP deployment targets
- Performance benchmarks and optimization pass
- Community contribution guidelines and issue triage
Exit criteria
- Framework can be extended with plugins, deploys to multiple clouds, and handles high traffic with 99.9% uptime SLA.
Build first
Build first, skip first, and watchouts
First things to build
- Project scaffolding CLI that generates a `package.json`, `pages/index.js`, and `next.config.js`-like config.
- A basic HTTP server in Node.js that resolves file-system routes and returns React-rendered HTML.
- A webpack/Rust bundler configuration that compiles the app for production with code splitting.
- An AWS CloudFormation template to provision Lambda@Edge and CloudFront.
- GitHub repo with CI setup (GitHub Actions) for automated testing on PRs.
Not to build yet
- Full-featured IDE integration (just CLI for now).
- Custom analytics dashboards with ML-driven insights (start with basic counters).
- Third-party authentication provider integrations beyond basic email/password (phase 4).
- Multi-region edge deployment (single region initially).
- Plugin marketplace or community extensions (focus on core stability first).
Risks / blockers
- Vercel/Next.js ecosystem dominance; developers may not switch without a compelling reason.
- Complexity of implementing a high-performance Rust bundler; could delay MVP.
- Reliance on AWS serverless may limit flexibility for non-AWS enterprises, narrowing TAM.
- Security vulnerabilities in dependencies (as seen in source repo with postcss) could impact trust.
- Lack of clear CI and testing in the initial phases may lead to quality issues.
Builder prompts
Derived builder prompts
Master
Master context prompt
Expand prompt
You are building a fresh implementation inspired by the vercel/next.js repository. Treat the repository as a reverse-engineering reference, not as the default destination codebase. Infer the product, architecture, entities, and flows from the reference repository, then rebuild the core system intentionally from scratch. Do not blindly clone the original repo. Do not default to patching or refactoring it in place. Build in small phases and keep the first version focused and maintainable. Product thesis: Provide React developers with a framework and cloud platform that drastically reduces the time and complexity of building and scaling full-stack applications on AWS, while offering a clear path to enterprise reliability and support. Commercial/product framing: Enterprises already invested in AWS want a Next.js-like developer experience but with deeper cloud integration, predictable costs, and a single vendor for framework and hosting. By coupling the framework tightly with AWS services, we can deliver superior performance and operational simplicity compared to generic platforms. Target user: Full-stack developers and platform engineers in AWS-centric organizations building customer-facing web applications with React. MVP scope: - File-system based routing with support for pages and API routes. - React Server Components with streaming and suspense. - Static generation (SSG) and server-side rendering (SSR) modes. - Zero-config deployment to AWS Lambda@Edge and CloudFront via CLI. - Automatic code splitting and optimized production builds. - Built-in environment variable management with `.env` support. - Basic analytics dashboard showing request count and latency. - Developer documentation and a ‘create-my-app’ scaffolding CLI. Stack assumptions: - Primary language: JavaScript/TypeScript for framework, with Rust modules for high-performance bundling/compilation (evidenced by Cargo.toml presence). - Bundler: likely a custom Rust-based bundler (like Turbopack) used for development and production builds. - Server runtime: Node.js for server components, with ability to target AWS Lambda and other serverless environments. - Rendering: React Server Components (RSC) streaming protocol. - Routing: file-system based, with dynamic routes, middleware pattern. - Package manager: pnpm (evidenced by pnpm-lock.yaml). - CI/CD: GitHub Actions (evidenced by .github/actions subdirectories), though currently missing in evidence flags, but planned. - Observability: logs and metrics exportable to CloudWatch (not yet implemented in MVP but planned). Key entities: - Project: id, name, config (route types, plugins), environmentVariables, deploymentTarget - Deployment: id, projectId, status, url, logs - Page: path, route, getStaticProps, getServerSideProps, component - User: id, email, orgId, role Core pages / routes / flows: - Create new project (CLI: `create my-app`): Scaffolds a new Next.js-like project with default configuration and local dev server. - Local development with hot reload (`localhost:3000`): Developer runs `npm run dev` to see live preview of app with RSC, SSR, and file-based routing. - Deploy project (CLI: `deploy`): Builds the project for production and deploys to the hosting platform, returning a live URL. - View deployment analytics (Dashboard: `/projects/[id]/analytics`): Shows request volume, latency, and error rates for the deployed project. - Manage environment variables (Dashboard: `/projects/[id]/settings/env`): Add, edit, or remove environment variables that are injected at build and runtime. - Link local project to platform (CLI: `link`): Connects a local project to an existing platform project for deployments and sync. Backend services / modules: - Routing Engine: Handles file-system based route resolution, mapping URL paths to page components and server functions. - Build System: Compiles and bundles the application, including Rust-based optimizer, code splitting, and static generation. - Deployment Service: Manages project builds and deploys to cloud infrastructure (e.g., S3 + CloudFront + Lambda). - Analytics Service: Collects and displays request metrics, using serverless function logs and edge data. - CLI: Command-line interface for scaffolding, dev server, and deployment commands. Do not build yet: - Full-featured IDE integration (just CLI for now). - Custom analytics dashboards with ML-driven insights (start with basic counters). - Third-party authentication provider integrations beyond basic email/password (phase 4). - Multi-region edge deployment (single region initially). - Plugin marketplace or community extensions (focus on core stability first). Major risks / blockers: - Vercel/Next.js ecosystem dominance; developers may not switch without a compelling reason. - Complexity of implementing a high-performance Rust bundler; could delay MVP. - Reliance on AWS serverless may limit flexibility for non-AWS enterprises, narrowing TAM. - Security vulnerabilities in dependencies (as seen in source repo with postcss) could impact trust. - Lack of clear CI and testing in the initial phases may lead to quality issues. Work in phases. After each phase, summarize what was built, what remains, and which assumptions from the reference repo you intentionally did or did not keep.
Phase 1
Phase 1 foundation prompt
Expand prompt
Phase 1 foundation Objective: Build a minimal file-system router and server-side rendering engine that can serve React components. Deliverables: - Basic `pages/` directory routing - Simple dev server with hot reload - Production build with code splitting - CLI with `init` and `dev` commands - Exit: Can create a new project, run `dev`, navigate between pages, and build a static production bundle. Rules: - Start by reverse engineering the product shape from the reference repo, then create a clean fresh project structure. - Set up the minimum schema, services, routes, and project structure required for the MVP. - Avoid polish work, avoid optional abstractions, and avoid copying implementation details you do not understand. Start by reverse engineering the reference repository, then implement the fresh build in the smallest clean sequence.
Phase 2
Phase 2 core flow prompt
Expand prompt
Phase 2 core flow Objective: Integrate with AWS Lambda@Edge to enable zero-config deployment from the CLI. Deliverables: - AWS Lambda wrapper for server components - CloudFront distribution setup via CLI - Deployment lifecycle management (build, upload, activate) - Basic dashboard with project list and deploy button - Exit: User can run `deploy` and get a live URL serving the application, with ability to view deployments in a web dashboard. Rules: - Implement the core pages, routes, and backend modules needed for the happy path in the fresh build. - Use the reference repo for behavior and architecture cues, not as the code target. - Preserve maintainability and add only the minimum comments needed. Start by reverse engineering the reference repository, then implement the fresh build in the smallest clean sequence.
Phase 3
Phase 3 polish/refactor prompt
Expand prompt
Phase 3 polish and refactor Objective: Add React Server Components, streaming, dynamic routes, and incremental static regeneration. Deliverables: - Server Components support with streaming - Dynamic route segments (e.g., [id]) - ISR with SWR caching on edge - API routes (pages/api) - Environment variable injection - Exit: Developers can use RSC, dynamic routes, and API routes; app deploys with automatic ISR. Rules: - Refine the fresh implementation without introducing a large refactor. - Improve validation, edge cases, and developer ergonomics where the core flow already exists. - Prefer targeted cleanup over architecture churn or feature creep. Start by reverse engineering the reference repository, then implement the fresh build in the smallest clean sequence.
Deploy
Deploy/finalization prompt
Expand prompt
Deploy and finalization Objective: Prepare the implementation for release, verification, and handoff. Deliverables: - Verify the main flows work. - Check configuration, environment assumptions, and release blockers. - Summarize remaining risks and suggested follow-up work. Rules: - Do not add speculative infrastructure. - Focus on practical release readiness, tests, and explicit known gaps versus the reference repo. Start by reverse engineering the reference repository, then implement the fresh build in the smallest clean sequence.
Bugfix
Bugfix/refinement prompt
Expand prompt
Bugfix and refinement Objective: Fix the specific bug or implementation gap in the fresh build while preserving the established architecture. Deliverables: - Reproduce the issue in the rebuilt implementation. - Patch the smallest reliable fix. - Explain what caused it, how to verify the fix, and whether the reference repo suggests an architecture guardrail you missed. Rules: - Inspect the fresh implementation before editing. - Do not rewrite working systems just to fix a localized issue. Start by reverse engineering the reference repository, then implement the fresh build in the smallest clean sequence.