AI PRD Workflow

The LinkSnip URL Shortener project is built using the following stack:

• Runtime: Node.js 20+ with TypeScript 5.x (strict mode)
• Framework: Express.js (REST API)
• Database: PostgreSQL 16 (URL and analytics storage)
• Cache: Redis 7 (redirect caching)
• Frontend: React 18 with Vite (analytics dashboard)
• Testing: Jest (unit/integration), Playwright (e2e)
• Deployment: Docker with docker-compose

To prevent uncontrolled code generation, the workflow requires a strict two-phase process:

Phase 1: Planning (No Code)

The agent must analyze requirements and present a plan including:

• Files to create or modify
• Key components, data structures, and APIs
• Proposed implementation sequence
• Technical decisions and trade-offs
• Potential impacts on existing functionality

Crucial: The agent must wait for explicit user approval before moving to Phase 2.

Phase 2: Implementation (After Approval Only)

Once approved, the agent implements the plan in logical segments, explains complex sections, and performs a self-review.

To allow users to specify custom identifiers for short URLs, extend the POST /api/urls endpoint to accept an optional alias field.

Validation Rules:

• Length: 3 to 30 characters.
• Format: Alphanumeric and hyphens only (Regex: ^[a-zA-Z0-9-]{3,30}$).
• Reserved Aliases: Reject specific system aliases such as api, docs, health, or admin with a 400 Bad Request.
• Uniqueness: If the alias is already in use, return a 409 Conflict error.

Ensure all submitted URLs are safe and valid during the creation process:

• Protocol Validation: Must be a valid http:// or https:// URL.
• Pattern Rejection: Reject URLs containing suspicious patterns, specifically data: URIs and javascript: URIs.
• Security (Optional): Integrate a malware blocklist API check at the time of creation.

When different project documents provide conflicting instructions, follow this strict order of authority:

1. PRD.md (Highest authority)
2. FEATURES.md
3. RULES.md
4. RFCs
5. Generated plans (Lowest authority)

Important: If the prompt's generic guidance conflicts with RULES.md, RULES.md always wins. Never resolve contradictions silently. You must state the contradiction, specify which artifact you followed and why, and flag the conflicting artifact for correction.

The project uses a layered architecture. Each layer must reside in its own directory under src/:

1. Routes
2. Controllers
3. Services
4. Repositories

Additional requirements:

• Place shared types in src/types/.
• Use environment variables for all configuration; do not hardcode values.

The system follows these architectural patterns:

• Layered Architecture: Express app organized as routes -> controllers -> services -> repositories.
• Caching: Redis cache-aside pattern used for high-performance redirect lookups.
• Infrastructure: Docker Compose orchestration including Node.js, PostgreSQL, and Redis services.

If instructions in the prompt conflict with project documentation, follow this hierarchy of authority:

1. PRD.md (Highest)
2. FEATURES.md
3. RULES.md
4. RFCs
5. generated plans (Lowest)

Note: RULES.md always overrides the generic guidance in the implementation prompt. If a contradiction is found, the agent must not resolve it silently; it must state which artifact it followed and why, then flag the other for correction.