Product Requirements Document (PRD): Project Phoenix

1. Executive Summary

Project Phoenix is a centralized web marketplace designed to "resurrect" abandoned side projects. It allows developers to offload codebases they no longer have the time to maintain while ensuring they receive long-term attribution. For "adopters"—including junior developers and indie hackers—it provides a validated technical foundation to build upon. The platform facilitates the entire lifecycle of a project hand-off, from GitHub import and automated tech-stack detection to legal transfer workflows and automated credit management.

2. Problem Statement

The developer community suffers from "Side Project Fatigue," where thousands of innovative codebases are abandoned due to burnout or shifting priorities. This leads to:

Lost Potential: Valuable logic and intellectual property sit idle in unmaintained repositories.
Lack of Formal Hand-off: There is no standard, secure way to transfer project "leadership" without losing the original creator's legacy.
High Barrier to Entry: Junior developers struggle to find real-world projects that are "ready for adoption" with clear permission from the owner.

3. Goals & Success Metrics

Resurrection Rate: 15% of listed projects should successfully transfer ownership within the first 6 months.
Attribution Integrity: 100% of resurrected projects must maintain an automated CREDITS.md file or README badge.
User Growth: Acquire 5,000 active developers within the first year.
Time-to-Import: A "one-click" import should take less than 20 seconds for standard repositories.

4. User Personas

The Burned-out Creator (The "Bury-er"): A senior dev with 10+ stale repos. They want a clean break but want their name to stay on the project if it ever goes viral.
The Portfolio Builder (The "Resurrector"): A junior dev looking for a codebase with existing architecture to learn from and improve for their resume.
The Indie Hacker (The "Operator"): Someone looking for a "validated MVP" to polish and monetize, willing to negotiate a revenue share or buyout.
The OSPO/Maintainer: Open-source advocates looking to ensure critical libraries don't die with their original authors.

5. User Stories

As a Creator, I want to import my GitHub repo and tag it as "Seeking Lead Maintainer" so that I can stop responding to issues without deleting the code.
As an Adopter, I want to filter projects by "Next.js" and "High Potential" so that I can find a project that matches my skills.
As a Creator, I want the platform to automatically inject a CREDITS.md file so that my original contribution is legally and visually acknowledged by the new owner.
As an Adopter, I want to message the original owner privately to discuss the transition plan before the transfer is finalized.

6. Functional Requirements

6.1. GitHub Integration & Import

One-Click Import: Use GitHub OAuth to list user repos.
Stack Detection: Integrate specfy/stack-analyser and @netlify/build-info to automatically detect languages, frameworks, and build commands.
Status Tagging: Options: Seeking Lead Maintainer, For Sale, Needs UI/UX, Looking for Fork.

6.2. Adoption Workflow

Request System: Adopters submit a "Proposal" (proposal message + portfolio link).
Transfer Mechanism: Facilitate GitHub's native Transfer API or Add-Collaborator API (Admin role).
Waiting Period: Implement a 30-day "intent to adopt" window for abandoned projects where the owner is unresponsive.

6.3. Attribution Management

Automated CREDITS.md: Use license-checker-evergreen to generate a markdown file listing the original creator and all contributors.
README Badges: Provide a dynamic Shields.io-compatible badge: Resurrected on Project Phoenix.

6.4. Discovery & Search

Command Palette: A ⌘K search bar for rapid filtering.
Project Directory: A bento-grid layout showing "Health Scores" and tech stack badges.

6.5. Communication

Private Messaging: A Socket.io-based chat room scoped to each individual AdoptionRequest.

7. Technical Requirements

7.1. Tech Stack

Frontend: Next.js 15.1+ (utilizing React 19, use cache directive, and next/form).
Backend: NestJS 10.x with TypeScript.
Database: PostgreSQL with Prisma ORM.
Real-time: Socket.io with @socket.io/redis-adapter for scalability.
Styling: Tailwind CSS 3.4+ and ShadcnUI.

7.2. Infrastructure & Integrations

Hosting: Vercel (Frontend), Railway (Backend/DB/Redis).
Auth: NextAuth.js with GitHub OAuth (Scopes: repo, read:user).
Secrets: Doppler for centralized secret management across Vercel and Railway.
CI/CD: Turborepo 2.0 for monorepo orchestration and remote caching.

8. Data Model

8.1. Key Entities

User: id, githubId, username, email, reputationScore.
Project: id, githubRepoId, originalOwnerId, status (Enum), techStack (JSONB), healthScore.
Collaboration: (Explicit Join) projectId, userId, role (OWNER/MAINTAINER), assignedAt, isOriginalOwner (Boolean).
AdoptionRequest: id, projectId, applicantId, status (PENDING/ACCEPTED/REJECTED), proposalMessage.
Message: id, adoptionRequestId, senderId, content, createdAt.

9. API Specification

10. UI/UX Requirements

The Directory: Dense utility grid showing framework icons (Next.js, Python, etc.) and a "Time Abandoned" metric.
The Command Bar: ⌘K opens a Shadcn Command dialog for global search.
Project Detail: A Shadcn Sheet (sliding from right) showing the README summary and the "Adopt" button.
Theme: Modern "Zinc" palette with context-aware dark mode.

11. Non-Functional Requirements

Security: Encryption-at-rest for GitHub OAuth tokens; ReBAC via Prisma Extensions to ensure only participants can read messages.
Performance: All GET requests for the directory must be cached via Next.js use cache with a 5-minute revalidation.
Legal: Adoption flow must include a DCO (Developer Certificate of Origin) sign-off.

12. Out of Scope

In-browser code editing (IDE features).
Automatic deployment of adopted projects to the cloud.
Monetization/Escrow (Reserved for Phase 2).

13. Risks & Mitigations

Risk: Users might use the platform to "hijack" active projects.
Mitigation: Only allow imports from repositories where the user has admin rights; implement a "Report Misuse" button.
Risk: GitHub API Rate Limits.
Mitigation: Implement aggressive caching of repository metadata and use Webhooks for updates.

14. Implementation Tasks

Phase 1: Project Setup

[ ] Initialize Turborepo with Next.js 15.1 and NestJS 10.x
[ ] Configure Tailwind CSS and install ShadcnUI components
[ ] Set up Prisma with PostgreSQL and define initial schema
[ ] Configure Doppler for environment variable syncing

Phase 2: Identity & GitHub Core

[ ] Implement NextAuth.js with GitHub Provider (Scopes: repo, user:email)
[ ] Create OAuth token encryption utility in NestJS
[ ] Build User Profile sync (GitHub metadata to local DB)

Phase 3: The Graveyard (Import)

[ ] Build Repo Picker UI using Shadcn Table
[ ] Integrate @netlify/build-info for framework detection
[ ] Implement specfy/stack-analyser logic in the NestJS worker
[ ] Create "Bury Repository" endpoint to save projects to DB

Phase 4: The Marketplace (Discovery)

[ ] Build the Bento-grid directory with Tailwind
[ ] Implement ⌘K search using Shadcn Command component
[ ] Create "Quick View" using Shadcn Sheet for README previews
[ ] Add server-side caching using Next.js 15 use cache

Phase 5: Adoption & Messaging

[ ] Create AdoptionRequest state machine (Pending -> Accepted)
[ ] Set up Socket.io Gateway in NestJS
[ ] Implement WsGuard for room-based message authorization
[ ] Build real-time chat UI with useOptimistic for instant feedback

Phase 6: Attribution & Transfer

[ ] Implement license-checker-evergreen logic to aggregate contributors
[ ] Create automated CREDITS.md generator using Markdown markers
[ ] Build the "Transfer Finalization" workflow (Trigger GitHub Transfer API)
[ ] Integrate DCO (Developer Certificate of Origin) checkbox in the adoption flow

Phase 7: Deployment & Launch

[ ] Configure Vercel for Frontend with Remote Caching
[ ] Deploy NestJS and Redis to Railway
[ ] Set up CORS policies for dynamic Vercel Preview URLs
[ ] Run final security audit on GitHub token storage