From d7a3d4c61f74693e64ee383f5c40e7ed79c62a14 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Fri, 15 Aug 2025 11:53:29 +0000 Subject: [PATCH] feat: implement new landing page with blueish glass morphism design - Complete design system setup with blueish-whiteish color palette - Add glass morphism CSS utilities and modern Inter/Poppins fonts - Create compelling hero section with animated background elements - Build features section with glass cards showcasing 6 key benefits - Integrate all components into main page.tsx with responsive design - Optimize layout with proper spacing and user flow - Add footer with additional CTAs and branding The new landing page follows modern UI/UX best practices with: - Blueish-whiteish glass morphism theme - Clean typography with Inter/Poppins fonts - No gradients in buttons as requested - Responsive design for all devices - Smooth animations and hover effects --- CLAUDE.md | 64 +++++ app/globals.css | 246 +++++++++++++----- app/page.tsx | 58 ++++- components/landing/FeaturesSection.tsx | 105 ++++++++ components/landing/HeroSection.tsx | 103 ++++++++ documentation/app_flowchart.md | 19 ++ documentation/backend_structure_document.md | 148 +++++++++++ documentation/cursor_project_rules.mdc | 98 +++++++ documentation/frontend_guidelines_document.md | 121 +++++++++ .../project_requirements_document.md | 91 +++++++ documentation/security_guideline_document.md | 134 ++++++++++ 11 files changed, 1123 insertions(+), 64 deletions(-) create mode 100644 CLAUDE.md create mode 100644 components/landing/FeaturesSection.tsx create mode 100644 components/landing/HeroSection.tsx create mode 100644 documentation/app_flowchart.md create mode 100644 documentation/backend_structure_document.md create mode 100644 documentation/cursor_project_rules.mdc create mode 100644 documentation/frontend_guidelines_document.md create mode 100644 documentation/project_requirements_document.md create mode 100644 documentation/security_guideline_document.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..783a84f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,64 @@ +# Claude Code Task Management Guide + +## Documentation Available + +📚 **Project Documentation**: Check the documentation files in this directory for project-specific setup instructions and guides. +**Project Tasks**: Check the tasks directory in documentation/tasks for the list of tasks to be completed. Use the CLI commands below to interact with them. + +## MANDATORY Task Management Workflow + +🚨 **YOU MUST FOLLOW THIS EXACT WORKFLOW - NO EXCEPTIONS** 🚨 + +### **STEP 1: DISCOVER TASKS (MANDATORY)** +You MUST start by running this command to see all available tasks: +```bash +task-manager list-tasks +``` + +### **STEP 2: START EACH TASK (MANDATORY)** +Before working on any task, you MUST mark it as started: +```bash +task-manager start-task +``` + +### **STEP 3: COMPLETE OR CANCEL EACH TASK (MANDATORY)** +After finishing implementation, you MUST mark the task as completed, or cancel if you cannot complete it: +```bash +task-manager complete-task "Brief description of what was implemented" +# or +task-manager cancel-task "Reason for cancellation" +``` + +## Task Files Location + +📁 **Task Data**: Your tasks are organized in the `documentation/tasks/` directory: +- Task JSON files contain complete task information +- Use ONLY the `task-manager` commands listed above +- Follow the mandatory workflow sequence for each task + +## MANDATORY Task Workflow Sequence + +🔄 **For EACH individual task, you MUST follow this sequence:** + +1. 📋 **DISCOVER**: `task-manager list-tasks` (first time only) +2. 🚀 **START**: `task-manager start-task ` (mark as in progress) +3. 💻 **IMPLEMENT**: Do the actual coding/implementation work +4. ✅ **COMPLETE**: `task-manager complete-task "What was done"` (or cancel with `task-manager cancel-task "Reason"`) +5. 🔁 **REPEAT**: Go to next task (start from step 2) + +## Task Status Options + +- `pending` - Ready to work on +- `in_progress` - Currently being worked on +- `completed` - Successfully finished +- `blocked` - Cannot proceed (waiting for dependencies) +- `cancelled` - No longer needed + +## CRITICAL WORKFLOW RULES + +❌ **NEVER skip** the `task-manager start-task` command +❌ **NEVER skip** the `task-manager complete-task` command (use `task-manager cancel-task` if a task is not planned, not required, or you must stop it) +❌ **NEVER work on multiple tasks simultaneously** +✅ **ALWAYS complete one task fully before starting the next** +✅ **ALWAYS provide completion details in the complete command** +✅ **ALWAYS follow the exact 3-step sequence: list → start → complete (or cancel if not required)** \ No newline at end of file diff --git a/app/globals.css b/app/globals.css index 0d27128..0dc46f5 100644 --- a/app/globals.css +++ b/app/globals.css @@ -1,88 +1,197 @@ -@import url('https://fonts.googleapis.com/css2?family=Parkinsans:wght@300..800&display=swap'); +@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&family=Poppins:wght@300;400;500;600;700;800&display=swap'); @tailwind base; @tailwind components; @tailwind utilities; .logo-text { - font-family: Parkinsans, sans-serif; + font-family: 'Inter', sans-serif; + font-weight: 600; } @layer utilities { .text-balance { text-wrap: balance; } + + /* Glass Morphism Utilities */ + .glass { + background: var(--glass-bg); + backdrop-filter: blur(var(--glass-blur)); + -webkit-backdrop-filter: blur(var(--glass-blur)); + border: 1px solid var(--glass-border); + box-shadow: 0 8px 32px var(--glass-shadow); + } + + .glass-sm { + background: var(--glass-bg); + backdrop-filter: blur(var(--glass-blur)); + -webkit-backdrop-filter: blur(var(--glass-blur)); + border: 1px solid var(--glass-border); + box-shadow: 0 4px 16px var(--glass-shadow); + } + + .glass-lg { + background: var(--glass-bg); + backdrop-filter: blur(var(--glass-blur)); + -webkit-backdrop-filter: blur(var(--glass-blur)); + border: 1px solid var(--glass-border); + box-shadow: 0 12px 48px var(--glass-shadow); + } + + .glass-hover { + transition: all 0.3s ease; + } + + .glass-hover:hover { + background: rgba(255, 255, 255, 0.35); + transform: translateY(-2px); + box-shadow: 0 12px 40px rgba(0, 0, 0, 0.15); + } + + .dark .glass-hover:hover { + background: rgba(40, 50, 80, 0.35); + } + + /* Typography Utilities */ + .font-inter { + font-family: 'Inter', sans-serif; + } + + .font-poppins { + font-family: 'Poppins', sans-serif; + } + + /* Gradient Backgrounds */ + .bg-gradient-blue-white { + background: linear-gradient(135deg, #f8fafc 0%, #e2e8f0 50%, #dbeafe 100%); + } + + .dark .bg-gradient-blue-white { + background: linear-gradient(135deg, #0f172a 0%, #1e293b 50%, #1e3a8a 100%); + } } @layer base { :root { - --background: 0 0% 100%; - --foreground: 240 10% 3.9%; + /* Blueish-Whiteish Color Palette */ + --background: 220 20% 98%; + --foreground: 220 15% 15%; + + /* Primary Blue Tones */ + --primary: 220 85% 55%; + --primary-foreground: 0 0% 100%; + --primary-light: 220 85% 65%; + --primary-dark: 220 85% 45%; + + /* Secondary Blue Tones */ + --secondary: 210 70% 95%; + --secondary-foreground: 220 15% 20%; + + /* Accent Blue */ + --accent: 200 80% 60%; + --accent-foreground: 0 0% 100%; + + /* Neutral Whites and Light Grays */ --card: 0 0% 100%; - --card-foreground: 240 10% 3.9%; + --card-foreground: 220 15% 15%; --popover: 0 0% 100%; - --popover-foreground: 240 10% 3.9%; - --primary: 240 5.9% 10%; - --primary-foreground: 0 0% 98%; - --secondary: 240 4.8% 95.9%; - --secondary-foreground: 240 5.9% 10%; - --muted: 240 4.8% 95.9%; - --muted-foreground: 240 3.8% 46.1%; - --accent: 240 4.8% 95.9%; - --accent-foreground: 240 5.9% 10%; + --popover-foreground: 220 15% 15%; + + /* Muted Tones */ + --muted: 220 15% 95%; + --muted-foreground: 220 10% 45%; + + /* Destructive */ --destructive: 0 84.2% 60.2%; - --destructive-foreground: 0 0% 98%; - --border: 240 5.9% 90%; - --input: 240 5.9% 90%; - --ring: 240 10% 3.9%; - --chart-1: 12 76% 61%; - --chart-2: 173 58% 39%; - --chart-3: 197 37% 24%; - --chart-4: 43 74% 66%; - --chart-5: 27 87% 67%; - --radius: 0.5rem; - --sidebar-background: 0 0% 98%; - --sidebar-foreground: 240 5.3% 26.1%; - --sidebar-primary: 240 5.9% 10%; - --sidebar-primary-foreground: 0 0% 98%; - --sidebar-accent: 240 4.8% 95.9%; - --sidebar-accent-foreground: 240 5.9% 10%; - --sidebar-border: 220 13% 91%; - --sidebar-ring: 217.2 91.2% 59.8%; + --destructive-foreground: 0 0% 100%; + + /* Borders and Inputs */ + --border: 220 15% 85%; + --input: 220 15% 90%; + --ring: 220 85% 55%; + + /* Glass Morphism Variables */ + --glass-bg: rgba(255, 255, 255, 0.25); + --glass-border: rgba(255, 255, 255, 0.18); + --glass-shadow: rgba(0, 0, 0, 0.1); + --glass-blur: 10px; + + /* Chart colors */ + --chart-1: 220 85% 55%; + --chart-2: 210 70% 60%; + --chart-3: 200 75% 65%; + --chart-4: 190 80% 70%; + --chart-5: 180 85% 75%; + + --radius: 0.75rem; + --sidebar-background: 0 0% 100%; + --sidebar-foreground: 220 15% 15%; + --sidebar-primary: 220 85% 55%; + --sidebar-primary-foreground: 0 0% 100%; + --sidebar-accent: 210 70% 95%; + --sidebar-accent-foreground: 220 15% 15%; + --sidebar-border: 220 15% 85%; + --sidebar-ring: 220 85% 55%; } .dark { - --background: 240 10% 3.9%; - --foreground: 0 0% 98%; - --card: 240 10% 3.9%; - --card-foreground: 0 0% 98%; - --popover: 240 10% 3.9%; - --popover-foreground: 0 0% 98%; - --primary: 0 0% 98%; - --primary-foreground: 240 5.9% 10%; - --secondary: 240 3.7% 15.9%; - --secondary-foreground: 0 0% 98%; - --muted: 240 3.7% 15.9%; - --muted-foreground: 240 5% 64.9%; - --accent: 240 3.7% 15.9%; - --accent-foreground: 0 0% 98%; + /* Dark Mode Blueish-Whiteish Palette */ + --background: 220 25% 8%; + --foreground: 220 15% 90%; + + /* Primary Blue Tones (Darker) */ + --primary: 220 75% 65%; + --primary-foreground: 0 0% 100%; + --primary-light: 220 80% 75%; + --primary-dark: 220 70% 55%; + + /* Secondary Dark Blues */ + --secondary: 220 20% 15%; + --secondary-foreground: 220 15% 90%; + + /* Accent Blue */ + --accent: 200 70% 70%; + --accent-foreground: 220 25% 8%; + + /* Dark Cards */ + --card: 220 20% 12%; + --card-foreground: 220 15% 90%; + --popover: 220 20% 12%; + --popover-foreground: 220 15% 90%; + + /* Muted Tones */ + --muted: 220 15% 18%; + --muted-foreground: 220 10% 65%; + + /* Destructive */ --destructive: 0 62.8% 30.6%; --destructive-foreground: 0 0% 98%; - --border: 240 3.7% 15.9%; - --input: 240 3.7% 15.9%; - --ring: 240 4.9% 83.9%; - --chart-1: 220 70% 50%; - --chart-2: 160 60% 45%; - --chart-3: 30 80% 55%; - --chart-4: 280 65% 60%; - --chart-5: 340 75% 55%; - --sidebar-background: 240 5.9% 10%; - --sidebar-foreground: 240 4.8% 95.9%; - --sidebar-primary: 224.3 76.3% 48%; + + /* Borders and Inputs */ + --border: 220 15% 20%; + --input: 220 15% 25%; + --ring: 220 75% 65%; + + /* Dark Mode Glass Morphism */ + --glass-bg: rgba(30, 40, 60, 0.25); + --glass-border: rgba(255, 255, 255, 0.08); + --glass-shadow: rgba(0, 0, 0, 0.3); + + /* Chart colors */ + --chart-1: 220 75% 65%; + --chart-2: 210 70% 70%; + --chart-3: 200 65% 75%; + --chart-4: 190 60% 80%; + --chart-5: 180 55% 85%; + + --sidebar-background: 220 20% 12%; + --sidebar-foreground: 220 15% 90%; + --sidebar-primary: 220 75% 65%; --sidebar-primary-foreground: 0 0% 100%; - --sidebar-accent: 240 3.7% 15.9%; - --sidebar-accent-foreground: 240 4.8% 95.9%; - --sidebar-border: 240 3.7% 15.9%; - --sidebar-ring: 217.2 91.2% 59.8%; + --sidebar-accent: 220 15% 18%; + --sidebar-accent-foreground: 220 15% 90%; + --sidebar-border: 220 15% 20%; + --sidebar-ring: 220 75% 65%; } } @@ -90,7 +199,22 @@ * { @apply border-border; } + + html { + font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + } + body { @apply bg-background text-foreground; + font-family: 'Inter', sans-serif; + font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11'; + } + + h1, h2, h3, h4, h5, h6 { + font-family: 'Poppins', sans-serif; + font-weight: 600; + line-height: 1.2; } } diff --git a/app/page.tsx b/app/page.tsx index c401399..fd3c9ec 100644 --- a/app/page.tsx +++ b/app/page.tsx @@ -1,8 +1,60 @@ "use client" -import { Hero } from '@/components/ui/animated-hero' -import Image from 'next/image' +import HeroSection from '@/components/landing/HeroSection' +import FeaturesSection from '@/components/landing/FeaturesSection' +import { Button } from '@/components/ui/button' +import Link from 'next/link' export default function Home() { - return + return ( +
+ + + + {/* Footer */} +
+
+
+
+

+ Ready to Level Up Your Development? +

+

+ Join the community of developers who trust CodeGuide.dev for smarter, faster development. +

+ +
+ + + +
+
+ +
+

+ © 2024 CodeGuide.dev. Built with AI, for developers. +

+
+
+
+
+
+ ) } diff --git a/components/landing/FeaturesSection.tsx b/components/landing/FeaturesSection.tsx new file mode 100644 index 0000000..92953a6 --- /dev/null +++ b/components/landing/FeaturesSection.tsx @@ -0,0 +1,105 @@ +import { Card } from "@/components/ui/card"; + +const features = [ + { + icon: "🤖", + title: "AI-Powered Guidance", + description: "Get intelligent code suggestions and architecture recommendations based on best practices and modern patterns.", + color: "from-blue-500 to-cyan-500" + }, + { + icon: "⚡", + title: "Modern Templates", + description: "Start with production-ready templates featuring the latest tech stack and proven patterns.", + color: "from-purple-500 to-pink-500" + }, + { + icon: "🛡️", + title: "Best Practices", + description: "Built-in security guidelines, performance optimization tips, and code quality standards.", + color: "from-green-500 to-emerald-500" + }, + { + icon: "📊", + title: "Code Analytics", + description: "Track code quality metrics, identify bottlenecks, and improve your development workflow.", + color: "from-orange-500 to-red-500" + }, + { + icon: "🔄", + title: "Continuous Updates", + description: "Stay current with automatic updates reflecting the latest industry trends and standards.", + color: "from-teal-500 to-blue-500" + }, + { + icon: "🎯", + title: "Precision Tools", + description: "Fine-tuned AI models for specific languages, frameworks, and development scenarios.", + color: "from-indigo-500 to-purple-500" + } +]; + +export default function FeaturesSection() { + return ( +
+
+ + {/* Section Header */} +
+
+ Features +
+ +

+ Everything You Need to Build Better +

+ +

+ CodeGuide.dev provides comprehensive tools and guidance to accelerate your development workflow and improve code quality. +

+
+ + {/* Features Grid */} +
+ {features.map((feature, index) => ( + + {/* Icon */} +
+ {feature.icon} +
+ + {/* Title */} +

+ {feature.title} +

+ + {/* Description */} +

+ {feature.description} +

+ + ))} +
+ + {/* Call to Action */} +
+
+

+ Ready to Transform Your Development? +

+

+ Join thousands of developers who are already building better code with AI guidance. +

+ + +
+
+
+
+ ); +} \ No newline at end of file diff --git a/components/landing/HeroSection.tsx b/components/landing/HeroSection.tsx new file mode 100644 index 0000000..51ae378 --- /dev/null +++ b/components/landing/HeroSection.tsx @@ -0,0 +1,103 @@ +import { Button } from "@/components/ui/button"; +import Link from "next/link"; + +export default function HeroSection() { + return ( +
+ {/* Background Pattern */} +
+ + {/* Animated Background Elements */} +
+
+
+
+
+ +
+
+ + {/* Main Hero Card */} +
+ + {/* Badge */} +
+ ✨ AI-Powered Development +
+ + {/* Headline */} +

+ Build Better Code +
+ + With AI Guidance + +

+ + {/* Subtitle */} +

+ CodeGuide.dev transforms how you write code with intelligent AI assistance, + modern templates, and best practices that help you ship faster and smarter. +

+ + {/* CTA Buttons */} +
+ + + +
+
+ + {/* Stats Row */} +
+ {[ + { label: "Developers", value: "10K+" }, + { label: "Code Reviews", value: "50K+" }, + { label: "Hours Saved", value: "100K+" } + ].map((stat, i) => ( +
+
{stat.value}
+
{stat.label}
+
+ ))} +
+ +
+
+ + {/* Scroll Indicator */} +
+
+
+
+
+ + +
+ ); +} \ No newline at end of file diff --git a/documentation/app_flowchart.md b/documentation/app_flowchart.md new file mode 100644 index 0000000..0ab73e9 --- /dev/null +++ b/documentation/app_flowchart.md @@ -0,0 +1,19 @@ +flowchart TD +A[User] --> B[Browser sends request] +B --> C[Nextjs App Router] +C --> D[Render layout_tsx] +D --> E[Render page_tsx] +E --> F[Load UI components] +E --> G[Apply global css] +E --> H[Client side fetch] +H --> I[Call API data route] +I --> J[API route handler] +J --> K[Process request and business logic] +K --> L[Send response] +L --> E + +subgraph Webhook Flow + X[External service] --> Y[Call API webhooks route] + Y --> Z[Process webhook payload] + Z --> K +end \ No newline at end of file diff --git a/documentation/backend_structure_document.md b/documentation/backend_structure_document.md new file mode 100644 index 0000000..97009f4 --- /dev/null +++ b/documentation/backend_structure_document.md @@ -0,0 +1,148 @@ +# Backend Structure Document + +This document outlines the backend setup for the `codeguide-starter-pro` project. It explains how the server side is organized, how data can be managed, and how the application is hosted and maintained. Anyone reading this can understand the backend without needing a deep technical background. + +## 1. Backend Architecture + +- **Framework and Runtime** + - Built on Next.js using its App Router and API Routes + - Runs on Node.js in a serverless (Function-as-a-Service) model + - Code is written in TypeScript for type safety and maintainability + +- **Design Patterns** + - **File-based routing**: Each folder under `app/` represents a route, with its own page, layout, and API handlers + - **Co-located logic**: UI, data fetching, and server functions live side by side for each route + - **Serverless functions**: Backend code (in `api/`) is deployed as small, independent functions that scale on demand + +- **Scalability, Maintainability, Performance** + - **Scalability**: Serverless endpoints auto-scale in response to traffic spikes, so you don’t need to provision servers + - **Maintainability**: Modular structure keeps each feature self-contained, making it easy to update or extend without touching unrelated code + - **Performance**: Built-in caching at the edge via the hosting platform (e.g., Vercel’s CDN) minimizes latency for end users + +## 2. Database Management + +- **Current State** + - The starter project does not include a built-in database + - It’s designed to let you plug in the database of your choice when needed + +- **Recommended Options** + - **Relational (SQL)**: PostgreSQL or MySQL, using an ORM like Prisma for easy data modeling + - **NoSQL**: MongoDB or DynamoDB, for document-based or key-value storage + +- **Data Handling Practices** + - Use environment variables (`.env.local`) to store database connection strings securely + - Implement connection pooling or serverless-friendly adapters to manage database connections efficiently + - Structure access logic through an ORM or data-access layer to keep queries organized and safe + +## 3. Database Schema (Example) + +Below is a simple example schema in PostgreSQL for storing webhook events. You can adapt or expand this structure when you integrate a real database. + +```sql +-- Table to store incoming webhook events +drop table if exists webhook_events; +create table webhook_events ( + id serial primary key, + event_type varchar(100) not null, + payload jsonb not null, + received_at timestamp with time zone default now() +); + +-- Optional: Table to store users (if you add auth later) +create table users ( + id serial primary key, + email varchar(255) unique not null, + hashed_password varchar(255) not null, + created_at timestamp with time zone default now() +); +``` + +## 4. API Design and Endpoints + +- **Approach** + - Uses RESTful API principles via Next.js API Routes in the `app/api/` folder + - Each route corresponds to a serverless function handling HTTP methods (GET, POST, etc.) + - You can extend it with additional endpoints (`/api/users`, `/api/auth`, etc.) + +- **Key Endpoint** + - **POST /api/webhooks** + - Purpose: Receive and process external webhook payloads + - Input: JSON payload sent by third-party services + - Processing: Validate signature (if configured), parse payload, store or forward data + - Response: 200 OK (acknowledgement) or appropriate error code + +- **Future Endpoints** (examples) + - **GET /api/webhooks**: List or filter past webhook events + - **POST /api/auth/login**: User login, returning a JWT + - **GET /api/users/me**: Fetch current user profile (protected) + +## 5. Hosting Solutions + +- **Primary Platform**: Vercel (recommended for Next.js) + - **Benefits**: + - Automatic deployment from your Git repository + - Global CDN for both static assets and serverless functions + - Built-in SSL certificates and HTTP/2 support + - Simple environment variable management + +- **Alternative Platforms**: + - AWS (using Lambda + API Gateway + S3) + - Netlify Functions + - Google Cloud Functions or Cloud Run + +## 6. Infrastructure Components + +- **Serverless Functions** + - Each API route becomes an independent function that scales on demand + - No need to manage servers or runtime patches + +- **Content Delivery Network (CDN)** + - Static assets (CSS, fonts, images) and rendered pages are cached at the edge + - Reduces load times for users around the world + +- **Load Balancers** + - Handled transparently by the hosting platform, distributing requests to the nearest available function instance + +- **Caching** + - Edge caching for pages and assets + - In-memory or Redis cache (optional) for database query results or expensive computations + +## 7. Security Measures + +- **Authentication & Authorization** + - Not included by default, but you can add JWT-based or OAuth providers via NextAuth.js + - Protect API endpoints by checking user sessions or tokens in middleware + +- **Data Encryption** + - All traffic over HTTPS by default on modern hosting platforms + - Use encrypted environment variables for secrets (API keys, DB credentials) + +- **Input Validation & Sanitization** + - Validate incoming JSON fields to prevent malformed data + - Sanitize inputs to guard against injection attacks + +- **Webhook Signature Verification** + - Verify HMAC signatures or tokens on incoming webhooks to confirm authenticity + +- **Rate Limiting & Abuse Protection** + - Implement rate limiting on critical endpoints to prevent denial-of-service + - Use API gateway or middleware libraries for throttling + +## 8. Monitoring and Maintenance + +- **Logging** + - Built-in request and error logs via the hosting platform + - Optional: Integrate a third-party service like Sentry, Datadog, or Logflare for structured logs and alerts + +- **Performance Monitoring** + - Set up analytics and error tracking to catch slow endpoints or frequent errors + - Use uptime checks to be notified if the API becomes unresponsive + +- **Maintenance Strategies** + - Regularly update dependencies (Next.js, Node.js, libraries) to patch vulnerabilities and benefit from performance improvements + - Run scheduled tasks or cron jobs (e.g., with Vercel’s cron feature) for database cleanup or batch processing + - Automated tests and CI/CD pipeline to catch regressions before deployment + +## 9. Conclusion and Overall Backend Summary + +The `codeguide-starter-pro` backend is powered by Next.js API Routes running in a serverless environment, ensuring automatic scalability and minimal operational overhead. While it doesn’t include a database out of the box, it’s designed to let you connect any SQL or NoSQL datastore when needed. Security relies on HTTPS, secret management, and best practices around input validation and authentication. Hosting on Vercel provides a global CDN, automatic scaling, and easy deployments. Monitoring and maintenance tools keep the system healthy and up to date. Overall, this setup delivers a lightweight, maintainable backend foundation that can grow as your application’s needs evolve. \ No newline at end of file diff --git a/documentation/cursor_project_rules.mdc b/documentation/cursor_project_rules.mdc new file mode 100644 index 0000000..dda1120 --- /dev/null +++ b/documentation/cursor_project_rules.mdc @@ -0,0 +1,98 @@ +--- +description: Apply these rules when making changes to the project +globs: +alwaysApply: true +--- + +Update this rule if user requested changes to the project requirement, etc. +## Project Overview + +* **Type:** cursor_project_rules +* **Description:** This repository, `codeguide-starter-pro`, appears to be a starter project for a modern web application, built with Next.js App Router, TypeScript, and AI-driven code guidance. +* **Primary Goal:** Provide a production-ready Next.js starter template with App Router, TypeScript, and integrated AI-guided code standards. + +## Project Structure + +### Framework-Specific Routing + +* **Directory Rules:** + * Next.js 14 (App Router): `app/[route]/page.tsx` conventions + * Next.js (Pages Router): `pages/[route].tsx` pattern + * React Router 6: `src/routes/` with `createBrowserRouter` + +### Core Directories + +* **Versioned Structure:** + * app/api: Next.js 14 API routes with Route Handlers + * components: Shared React UI components + * fonts: Custom font assets loaded via Next.js font optimization + * .cursor/rules: Cursor IDE AI-assisted code guidance rules + +### Key Files + +* **Stack-Versioned Patterns:** + * app/layout.tsx: Next.js 14 root layout (metadata, global providers) + * app/page.tsx: Next.js 14 root page component + * app/api/webhooks/route.ts: Next.js 14 API Route Handler for webhooks + * globals.css: Global stylesheet imported at root layout + +## Tech Stack Rules + +* **Version Enforcement:** + * next@14: App Router required, no `getInitialProps` + * react@18: Use functional components with Hooks and Server Components + * typescript@4.9: Strict mode enabled, explicit return types + +## PRD Compliance + +* No PRD provided: adhere to general Next.js 14 and AI-guidance rules + +## App Flow Integration + +* **Stack-Aligned Flow:** + * Next.js 14 Main Page Flow → `app/page.tsx` uses Server Components + * Next.js 14 Layout Flow → `app/layout.tsx` sets up providers and global UI + * Next.js 14 Webhook Flow → `app/api/webhooks/route.ts` uses Route Handlers + +## Best Practices + +* Next.js + * Use the App Router for all new routes in `app/` + * Co-locate data fetching with UI in Server Components + * Employ Route Handlers for API endpoints +* React + * Favor function components and React Hooks + * Use React Server Components where beneficial + * Avoid direct DOM manipulation; use refs and state +* TypeScript + * Enable `strict` mode in tsconfig.json + * Define explicit return types for all functions + * Use discriminated unions for component props + +## Rules + +* Derive folder/file patterns directly from `techStackDoc` versions +* If Next.js 14 App Router: enforce `app/` directory with nested route folders +* If Pages Router: use `pages/*.tsx` flat structure +* Mirror this logic for React Router, SvelteKit, etc. +* Never mix version patterns (no `pages/` in App Router projects) + +## Rules Metrics + +Before starting the project development, create a metrics file in the root of the project called + +`cursor_metrics.md`. + +### Instructions: + +* Each time a cursor rule is used as context, update `cursor_metrics.md`. +* Use the following format for `cursor_metrics.md`: + + # Rules Metrics + + ## Usage + The number of times rules is used as context + + * rule-name.mdc: 5 + * another-rule.mdc: 2 + * ...other rules \ No newline at end of file diff --git a/documentation/frontend_guidelines_document.md b/documentation/frontend_guidelines_document.md new file mode 100644 index 0000000..0e2f4a8 --- /dev/null +++ b/documentation/frontend_guidelines_document.md @@ -0,0 +1,121 @@ +# Frontend Guideline Document + +## Frontend Architecture + +Our frontend is built on **Next.js** (App Router) and **React**, using **TypeScript** for type safety. + +• **Next.js App Router** provides file-based routing, co-locating page, layout, and server logic in the `app/` folder. +• **React** components drive the UI, split into server and client components as needed. +• **TypeScript** ensures compile-time checks and consistent interfaces. +• **Next.js API Routes** (in `app/api/`) let us handle webhooks or other server logic without a separate backend. + +This architecture supports: +• **Scalability:** Easily add new routes, pages, and API endpoints under `app/`. +• **Maintainability:** Clear folder structure (`app/`, `components/`, `fonts/`, `.cursor/`) and component reuse reduce cognitive overhead. +• **Performance:** Out-of-the-box code splitting, server-side rendering (SSR), static site generation (SSG), and API routes. + +## Design Principles + +1. **Usability:** We use semantic HTML, clear navigation, and straightforward interactions. Buttons, links, and forms follow predictable patterns. +2. **Accessibility:** We follow WCAG guidelines—semantic tags, ARIA attributes, keyboard navigation, and sufficient color contrast. +3. **Responsiveness:** Mobile-first CSS with flexible layouts (CSS Grid, Flexbox) ensures the app works smoothly on all devices. +4. **Consistency:** Shared layout (`layout.tsx`), global styles, and a design token system ensure a unified experience. +5. **Performance-First:** Minimizing bundle size, optimizing images, and lazy-loading heavy components. + +## Styling and Theming + +### Approach + +• **Global CSS:** `globals.css` defines resets, base typography, and CSS variables. +• **Component-Level CSS Modules:** `Component.module.css` for scoped styles, preventing clashes. +• **CSS Variables:** Manage color and spacing tokens in `:root` for easy theming. + +### Look & Feel + +We chose a **modern flat design** aesthetic—clean lines, minimal shadows, and bold typography. + +### Color Palette + +• **Primary:** #005F73 +• **Secondary:** #0A9396 +• **Accent:** #94D2BD +• **Background:** #F0FAF9 +• **Surface:** #FFFFFF +• **Text (dark):** #14213D +• **Text (light):** #F8F9FA + +### Typography + +We include custom fonts in `fonts/`: +• **Geist VF:** used for headings and body text for a distinctive, readable look. +• **Geist Mono VF:** used for code snippets and monospaced elements. + +Font loading is handled via Next.js’s built-in font optimization or imported in `globals.css`: +```css +@font-face { + font-family: 'Geist VF'; + src: url('/fonts/GeistVF.woff') format('woff'); +} +@font-face { + font-family: 'Geist Mono VF'; + src: url('/fonts/GeistMonoVF.woff') format('woff'); +} +:root { + --font-sans: 'Geist VF', sans-serif; + --font-mono: 'Geist Mono VF', monospace; +} +``` + +## Component Structure + +All UI is split into small, self-contained components under `/components`. + +• **Feature folders (optional):** Group related components (e.g., `Button/`, `Card/`) together. +• **Atomic approach:** Atoms (buttons, inputs), molecules (form groups), organisms (navbars), templates (pages). +• **Reusable props:** Components accept props for data and callbacks, keeping them stateless where possible. + +This component-based architecture: +• Enhances reusability and consistency. +• Simplifies testing and documentation. +• Makes onboarding new features straightforward. + +## State Management + +• **Local State:** We use React’s `useState` and `useReducer` for component-level state. +• **Global State:** For cross-component data, we rely on React’s `Context API`. Context providers wrap `layout.tsx`. +• **Future Scale:** If state logic grows complex, we can introduce lightweight libraries like **Zustand** or **Jotai**, or a full solution like **Redux Toolkit**. + +## Routing and Navigation + +• **File-based routing:** Any `app/[route]/page.tsx` becomes a route. +• **Layouts:** `layout.tsx` in a route folder defines shared UI for that segment. +• **Dynamic routes:** Use brackets (`[id]`) for dynamic segments. +• **Navigation:** `next/link` for client-side transitions, `useRouter` for programmatic navigation. + +## Performance Optimization + +1. **Code Splitting:** Automatic per-route splitting by Next.js. +2. **Dynamic Imports:** `next/dynamic` to lazy-load heavy components or charts. +3. **Image Optimization:** Use `next/image` for responsive, compressed images. +4. **Caching & Revalidation:** Leverage ISR (Incremental Static Regeneration) and `getStaticProps`/`getServerSideProps` where appropriate. +5. **Minified Assets:** Next.js builds minified JS and CSS bundles by default. + +## Testing and Quality Assurance + +• **Unit & Integration Tests:** `Jest` + `React Testing Library` to verify components, hooks, and utility functions. +• **End-to-End Tests:** **Cypress** or **Playwright** for critical user flows (login, form submission, navigation). +• **API Route Tests:** Use `supertest` or Next.js test helpers to simulate webhook calls. +• **Type Checking:** Continuous TypeScript checks prevent type regressions. +• **Linting:** `ESLint` with React and TypeScript plugins catch code issues early. +• **Formatting:** `Prettier` enforces consistent code style. + +## Developer Experience and Tooling + +• **`.cursor/rules/`:** Custom AI-powered rules for inline code guidance, suggestions, and documentation snippets via Cursor IDE. +• **Git Hooks:** Use `husky` to run linting and tests on `pre-commit`. +• **EditorConfig:** Maintains consistent tab sizes and encoding across editors. +• **VS Code Extensions:** Recommended: ESLint, Prettier, Tailwind (if adopted later), and Cursor. + +## Conclusion and Overall Frontend Summary + +This guideline lays out a clear, modern frontend setup using Next.js, React, and TypeScript. We follow a component-based architecture, flat design style, and strong conventions for scalability, maintainability, and performance. Accessibility, consistency, and developer productivity are top priorities. With built-in API routes for webhooks and AI-driven code guidance, this starter project accelerates development of production-ready web applications while maintaining a high standard of quality. \ No newline at end of file diff --git a/documentation/project_requirements_document.md b/documentation/project_requirements_document.md new file mode 100644 index 0000000..b11c67f --- /dev/null +++ b/documentation/project_requirements_document.md @@ -0,0 +1,91 @@ +# Project Requirements Document for `codeguide-starter-pro` + +## 1. Project Overview + +`codeguide-starter-pro` is a boilerplate template designed to jump-start modern web applications using Next.js with the App Router and TypeScript. It provides a structured, opinionated codebase that includes page and layout co-location, global styling, custom typography, and a built‐in serverless API endpoint for handling webhook payloads. The goal is to eliminate repetitive setup work and enforce best practices out of the box. + +The project is built to help developers focus on business logic instead of configuration. Key objectives include: +- Delivering a maintainable folder structure for scalable growth. +- Ensuring type safety and early error detection through TypeScript. +- Offering AI-powered code guidance via Cursor rules to maintain consistent code style. +Success is measured by how quickly a developer can clone the repo and extend it with new pages, styles, and API routes, and how well the built-in tools enforce quality standards. + +## 2. In-Scope vs. Out-of-Scope + +### In-Scope (Version 1) +- Next.js App Router structure (`app/`, `page.tsx`, `layout.tsx`) +- Global CSS (`globals.css`) and custom font integration (`fonts/` folder) +- A serverless webhook API endpoint (`api/webhooks/route.ts`) with basic request handling +- Dedicated `components/` directory for reusable UI elements +- `.cursor/rules/` configuration for AI-assisted coding standards and inline guidance +- TypeScript configuration and types for pages and API routes + +### Out-of-Scope (Later Phases) +- Authentication or user management flows +- Database integrations or ORM setup +- Production deployment pipelines (CI/CD scripts) beyond basic `npm run build` +- Comprehensive testing suite (unit/integration tests) +- Analytics tracking, logging, and monitoring integrations +- Internationalization (i18n) or multi-locale support + +## 3. User Flow + +A new developer picks up the project by cloning the Git repository and running `npm install` followed by `npm run dev`. They open `http://localhost:3000` in their browser, see a landing page wrapped by a shared layout (header, footer), and notice the global styles and custom fonts applied. From there, they explore `app/page.tsx` and `app/layout.tsx` to understand where to place new content. + +Next, they create a new UI component in `components/`, import it into a new route file under `app/`, and see it rendered instantly—thanks to Next.js fast refresh. They then examine the webhook endpoint in `api/webhooks/route.ts`, simulate incoming requests via `curl`, and confirm that the minimal request handler can be extended to process real event payloads. Throughout this process, the Cursor IDE plugin surfaces style and best-practice suggestions directly in the code editor. + +## 4. Core Features + +- **Next.js App Router**: File-based routing where each folder in `app/` co-locates page, layout, and styling. +- **TypeScript**: Enforces strong typing for components, props, and API payloads. +- **Global Styling**: `globals.css` for resets and base styles, with room for CSS Modules or other CSS-in-JS solutions. +- **Custom Typography**: Preloaded font files (`.woff`) managed in the `fonts/` directory. +- **Serverless Webhook Endpoint**: A template in `api/webhooks/route.ts` for receiving and processing external HTTP requests. +- **Components Directory**: Central location for reusable React UI components. +- **AI-Driven Code Guidance**: `.cursor/rules/` config files that instruct the Cursor IDE plugin on project-specific linting and suggestions. + +## 5. Tech Stack & Tools + +- **Frontend Framework**: Next.js (React) with the App Router +- **Language**: TypeScript +- **Styling**: CSS (global), with optional support for CSS Modules or Tailwind CSS +- **Runtime**: Node.js (serverless functions via Next.js API Routes) +- **AI Guidance**: Cursor IDE plugin with custom rules in `.cursor/rules/` +- **Package Manager**: npm or Yarn +- **Suggested IDEs**: VS Code with Cursor extension, ESLint, Prettier plugins + +## 6. Non-Functional Requirements + +- **Performance**: + - Initial page load TTFB < 200 ms for cached pages. + - Fast Refresh cycle within 500 ms for local development. +- **Security**: + - Validate and sanitize incoming webhook payloads. + - Use environment variables for secrets (.env.local). +- **Usability**: + - Responsive design by default (mobile-first). + - Accessible markup (semantic HTML, ARIA roles where needed). +- **Scalability**: + - Extendable folder structure to support dozens of routes/components. +- **Maintainability**: + - Enforce coding standards via Cursor rules and recommended ESLint/Prettier configs. + +## 7. Constraints & Assumptions + +- **Node.js Version**: Requires Node.js 16 or newer. +- **Browser Support**: Modern evergreen browsers (Chrome, Firefox, Edge, Safari). +- **Deployment Platform**: Assumes serverless hosting (e.g., Vercel, Netlify) for API routes. +- **Cursor Plugin**: Developer must install Cursor IDE extension to benefit from AI guidance. +- **Environment Variables**: Incoming webhook secrets and API keys must be set in `.env.local` before use. + +## 8. Known Issues & Potential Pitfalls + +- **Large Font Files**: Custom `.woff` fonts can bloat bundles—consider subsetting or lazy-loading fonts. +- **API Cold Starts**: Serverless functions may incur cold starts; mitigate with lightweight handlers or regional edge functions. +- **Cursor Rule Conflicts**: Custom AI rules might conflict with standard ESLint rules—ensure alignment or disable overlapping rules. +- **Lack of Testing**: No test suite is included; plan to integrate Jest and React Testing Library to avoid regressions. +- **Routing Edge Cases**: Deeply nested routes may require explicit layout handling; document best practices as the app grows. + +**End of PRD** + +This document provides a clear reference for AI-driven tooling and future technical specifications, ensuring precise guidance for everything from folder structure to API behavior. \ No newline at end of file diff --git a/documentation/security_guideline_document.md b/documentation/security_guideline_document.md new file mode 100644 index 0000000..4930a80 --- /dev/null +++ b/documentation/security_guideline_document.md @@ -0,0 +1,134 @@ +# Security Guidelines for codeguide-starter-pro + +This document provides comprehensive security recommendations for the **codeguide-starter-pro** repository, a modern Next.js application starter kit. It embeds essential security-by-design principles and best practices across authentication, data protection, API security, and infrastructure configuration. Follow these guidelines to ensure a secure, resilient, and maintainable codebase. + +--- + +## 1. Security by Design + +- **Threat Modeling**: Enumerate potential threats (e.g., unauthorized access, webhook spoofing, injection attacks) early in the design phase. Update as features evolve. +- **Secure Defaults**: Ensure all new files, routes, and components adopt secure settings by default rather than relying on opt-in security. +- **Defense in Depth**: Apply multiple layers of controls. For example, combine input validation, CSP headers, and output encoding to mitigate XSS. +- **Least Privilege**: Grant minimal permissions for environment variables, file system access, and third-party services. + +--- + +## 2. Authentication & Access Control + +Even if your starter project does not include authentication out of the box, consider these guidelines before adding protected routes: + +- **Use a Battle-Tested Library**: Adopt NextAuth.js or a custom solution using Passport.js; avoid rolling your own auth unless absolutely necessary. +- **Strong Password Policies**: If storing credentials, hash passwords using Argon2 or bcrypt with unique salts. Enforce complexity and minimum lengths (e.g., ≥12 characters). +- **Session Management**: + - Store sessions in a secure, server-side store (e.g., Redis). + - Set cookies with `Secure`, `HttpOnly`, and `SameSite=Strict` attributes. + - Implement idle and absolute timeouts. +- **JWT Best Practices** (if used): + - Select a robust algorithm (e.g., RS256) and never use `alg: none`. + - Validate `exp` and `aud` claims on every request. + - Rotate or refresh tokens regularly. +- **Role-Based Access Control (RBAC)**: + - Define clear roles (e.g., `user`, `admin`) and enforce server-side checks on every protected API route or page. + - Deny access by default (`default-deny` policy) and explicitly grant permissions as needed. +- **Multi-Factor Authentication (MFA)**: Provide optional or mandatory MFA for administrative or high-sensitivity areas. + +--- + +## 3. Input Handling & Processing + +- **Server-Side Validation**: Never trust client-side checks alone. Validate all incoming JSON, form data, and headers using a schema validation library (e.g., Zod, Joi). +- **SQL/NoSQL Injection**: Use parameterized queries or a reputable ORM (e.g., Prisma). Do not concatenate user input into queries. +- **Command Injection**: Avoid invoking shell commands with user input. If necessary, sanitize and use safe APIs (e.g., `child_process.spawn` with arguments array). +- **Prevent XSS**: + - Sanitize any HTML fragments before server-side rendering (e.g., DOMPurify). + - Use Next.js’s built-in escaping for interpolated values in React. + - Enforce a strict Content Security Policy (CSP) via HTTP headers. +- **CSRF Protection**: Use anti-CSRF tokens (e.g., `next-csrf` or built-in NextAuth.js CSRF support) for all state-changing POST/PUT/DELETE requests. +- **Redirect Validation**: If you implement redirects (e.g., after login), validate the `returnTo` URL against an allow-list to prevent open redirect attacks. +- **File Upload Security**: + - Restrict allowed file types and maximum sizes. + - Store user uploads outside the `public/` directory or on a dedicated object storage bucket with restricted permissions. + - Scan uploads for malware (e.g., ClamAV). + - Sanitize filenames to avoid path traversal. + +--- + +## 4. API & Webhook Security + +The `api/webhooks/route.ts` endpoint is an integration point for third-party services. Secure it as follows: + +- **Signature Verification**: Require providers to sign payloads (e.g., HMAC SHA-256). Reject requests with invalid or missing signatures. +- **Rate Limiting**: Throttle repeated requests from the same IP or webhook source to mitigate abuse or DoS. +- **HTTPS Only**: Enforce TLS (1.2+) for all incoming webhook calls and API requests. Redirect HTTP to HTTPS at the CDN or load-balancer level. +- **Input Validation**: Strictly validate webhook payload structure and types. Drop any unexpected fields. +- **Idempotency**: Design the webhook handler to be idempotent. Use a unique event ID to prevent duplicate processing. +- **Error Handling**: Return appropriate status codes (2xx for success, 4xx for client errors, 5xx for server errors). Do not leak stack traces in responses. + +--- + +## 5. Data Protection & Privacy + +- **Encrypt in Transit**: Use HTTPS everywhere (Next.js `next.config.js` as needed). +- **Encrypt at Rest**: + - Enable encryption for your database (e.g., AWS RDS encryption at rest). + - Encrypt backups and snapshots. +- **Secrets Management**: + - Store API keys, database credentials, and webhook secrets in environment variables or a dedicated vault (e.g., HashiCorp Vault, AWS Secrets Manager). + - Never check secrets into source control or `.cursor/rules/`. +- **PII Handling**: Mask or hash personally identifiable information before logging. Comply with GDPR/CCPA guidelines for user data deletion upon request. +- **Logging & Monitoring**: + - Centralize logs (e.g., Sentry, Datadog). Ensure no sensitive values are logged. + - Set log levels appropriately (avoid `debug` in production). + +--- + +## 6. Web Application Security Hygiene + +- **Security Headers** (set in `next.config.js` or a custom server): + - Strict-Transport-Security (HSTS) + - Content-Security-Policy (CSP) + - X-Frame-Options: DENY or `frame-ancestors` in CSP + - X-Content-Type-Options: nosniff + - Referrer-Policy: no-referrer or strict-origin-when-cross-origin +- **Cookie Settings**: + - `Secure` and `HttpOnly` flags + - `SameSite=Strict` or `Lax` as appropriate +- **Subresource Integrity (SRI)**: Use `integrity` attributes for any third-party scripts/styles. +- **Disable Debug in Production**: Set `NODE_ENV=production` and ensure any debug middleware (e.g., React DevTools) is disabled. + +--- + +## 7. Infrastructure & Configuration Management + +- **Environment Hardening**: + - Disable unused services on the hosting VM or container. + - Regularly apply OS and package updates. +- **Port Management**: Only expose necessary ports (e.g., 80, 443). Block internal ports via firewall rules. +- **CI/CD Security**: + - Use least-privileged CI service credentials. + - Store deployment secrets in the CI’s secure vault. + - Scan pull requests with SCA tools (e.g., Dependabot, Snyk) and fail builds on critical vulnerabilities. +- **Immutable Infrastructure**: Prefer container or serverless deployments to reduce drift and enforce consistency. + +--- + +## 8. Dependency Management + +- **Lockfiles**: Commit `package-lock.json` or `yarn.lock` for deterministic installs. +- **Regular Updates**: Schedule periodic dependency reviews and updates. Automate with Dependabot or Renovate. +- **Security Scanning**: Integrate `npm audit` or a dedicated SCA tool in your CI pipeline. Address high and critical vulnerabilities promptly. +- **Minimal Footprint**: Remove unused dependencies to shrink the attack surface. + +--- + +## 9. Testing and Validation + +- **Unit & Integration Tests**: Cover critical logic in API routes (especially `webhooks/route.ts`) and core components. +- **End-to-End Tests**: Simulate real user flows with Cypress or Playwright, including authentication and webhook events. +- **Fuzz Testing**: Optionally fuzz JSON parsers and input handlers to catch edge-case errors. +- **Penetration Testing**: Periodically engage in pen tests or use automated tools (e.g., OWASP ZAP, Burp Suite) against staging environments. + +--- + +## Conclusion +Adhering to these security guidelines ensures that **codeguide-starter-pro** remains a secure and reliable foundation for your Next.js application. Regularly revisit and update your security posture as new threats emerge and the project evolves. Always prioritize simplicity, least privilege, and defense in depth. \ No newline at end of file