Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# 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 <task_id>
```

### **STEP 3: COMPLETE EACH TASK (MANDATORY)**
After finishing implementation, you MUST mark the task as completed:
```bash
task-manager complete-task <task_id> "Brief description of what was implemented"
```

## 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 <task_id>` (mark as in progress)
3. 💻 **IMPLEMENT**: Do the actual coding/implementation work
4. ✅ **COMPLETE**: `task-manager complete-task <task_id> "What was done"`
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
❌ **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**

## Final Requirements

🚨 **CRITICAL**: Your work is not complete until you have:
1. ✅ Completed ALL tasks using the mandatory workflow
2. ✅ Committed all changes with comprehensive commit messages
3. ✅ Created a pull request with proper description

Remember: The task management workflow is MANDATORY, not optional!
238 changes: 155 additions & 83 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,133 +1,205 @@
[![CodeGuide](/codeguide-backdrop.svg)](https://codeguide.dev)
# 🔍 Webpage Analyzer

An AI-powered web application that analyzes landing pages and provides actionable copywriting and layout improvement suggestions. Simply enter any webpage URL to get instant, detailed feedback to optimize your content.

# CodeGuide Starter Lite
## ✨ Features

A modern web application starter template built with Next.js 14, featuring authentication, database integration.
- 🤖 **AI-Powered Analysis** - Uses JinaAI for content extraction and OpenAI for intelligent insights
- 🔒 **Secure Authentication** - User management powered by Clerk
- 📝 **Markdown Reports** - Detailed analysis reports in readable Markdown format
- 💾 **Report History** - Save and revisit past analyses locally
- 📱 **Responsive Design** - Works perfectly on desktop, tablet, and mobile
- ⚡ **Fast Analysis** - Get results in under 10 seconds
- 📥 **Download Reports** - Export analysis as `.md` files for offline use
- 🎨 **Beautiful UI** - Modern interface with smooth animations

## Tech Stack
## 🛠 Tech Stack

- **Framework:** [Next.js 14](https://nextjs.org/) (App Router)
- **Framework:** [Next.js 14](https://nextjs.org/) with App Router
- **Authentication:** [Clerk](https://clerk.com/)
- **AI Services:** [JinaAI](https://jina.ai/) + [OpenAI](https://openai.com/)
- **UI/UX:** [Tailwind CSS](https://tailwindcss.com/) + [shadcn/ui](https://ui.shadcn.com/) + [Framer Motion](https://framer.com/motion)
- **Forms:** [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/)
- **Markdown:** [marked](https://marked.js.org/) + [react-markdown](https://github.com/remarkjs/react-markdown)
- **Icons:** [Lucide React](https://lucide.dev/)
- **Database:** [Supabase](https://supabase.com/)
- **Styling:** [Tailwind CSS](https://tailwindcss.com/)
- **UI Components:** [shadcn/ui](https://ui.shadcn.com/)
- **Deployment:** [Vercel](https://vercel.com/)

## Prerequisites
## 🚀 Quick Start

### Prerequisites

Before you begin, ensure you have the following:
- Node.js 18+ installed
- A [Clerk](https://clerk.com/) account for authentication
- A [Supabase](https://supabase.com/) account for database
- Generated project documents from [CodeGuide](https://codeguide.dev/) for best development experience
- [Clerk](https://clerk.com/) account for authentication
- [JinaAI](https://jina.ai/) API key for content extraction
- [OpenAI](https://openai.com/) API key for analysis
- [Supabase](https://supabase.com/) project (optional, for future database features)

## Getting Started
### Installation

1. **Clone the repository**
```bash
git clone <repository-url>
cd codeguide-starter-pro
cd webpage-analyzer
```

2. **Install dependencies**
```bash
npm install
# or
yarn install
# or
pnpm install
```

3. **Environment Variables Setup**
- Copy the `.env.example` file to `.env`:
```bash
cp .env.example .env
```
- Fill in the environment variables in `.env` (see Configuration section below)

4. **Start the development server**
3. **Environment Setup**
```bash
npm run dev
# or
yarn dev
# or
pnpm dev
cp .env.example .env
```

5. **Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.**
4. **Configure environment variables** (see Configuration section)

## Configuration
5. **Start development server**
```bash
npm run dev
```

### Clerk Setup
1. Go to [Clerk Dashboard](https://dashboard.clerk.com/)
2. Create a new application
3. Go to API Keys
4. Copy the `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`
6. **Open [http://localhost:3000](http://localhost:3000)** in your browser

### Supabase Setup
1. Go to [Supabase Dashboard](https://app.supabase.com/)
2. Create a new project
3. Go to Project Settings > API
4. Copy the `Project URL` as `NEXT_PUBLIC_SUPABASE_URL`
5. Copy the `anon` public key as `NEXT_PUBLIC_SUPABASE_ANON_KEY`
## ⚙ Configuration

## Environment Variables
### Required Environment Variables

Create a `.env` file in the root directory with the following variables:
Create a `.env.local` file in the root directory:

```env
# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_publishable_key
CLERK_SECRET_KEY=your_secret_key
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key

# Supabase
# AI Services
JINAAI_API_KEY=your_jinaai_api_key
OPENAI_API_KEY=your_openai_api_key

# Supabase (Optional)
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
```

## Features
### Setup Instructions

#### 1. Clerk Authentication
- Visit [Clerk Dashboard](https://dashboard.clerk.com/)
- Create a new application
- Copy your Publishable Key and Secret Key from the API Keys section

- 🔐 Authentication with Clerk
- 📦 Supabase Database
- 🎨 Modern UI with Tailwind CSS
- 🚀 App Router Ready
- 🔄 Real-time Updates
- 📱 Responsive Design
#### 2. JinaAI Setup
- Sign up at [JinaAI](https://jina.ai/)
- Generate an API key from your dashboard
- Add to environment variables

## Project Structure
#### 3. OpenAI Setup
- Create account at [OpenAI](https://openai.com/)
- Generate an API key from your API keys section
- Add to environment variables

#### 4. Supabase (Optional)
- Create project at [Supabase Dashboard](https://app.supabase.com/)
- Copy Project URL and anon key from Project Settings > API

## 📁 Project Structure

```
codeguide-starter/
├── app/ # Next.js app router pages
├── components/ # React components
├── utils/ # Utility functions
├── public/ # Static assets
├── styles/ # Global styles
├── documentation/ # Generated documentation from CodeGuide
└── supabase/ # Supabase configurations and migrations
webpage-analyzer/
├── app/ # Next.js 14 App Router
│ ├── api/analyze/ # API route for webpage analysis
│ ├── globals.css # Global styles
│ ├── layout.tsx # Root layout
│ └── page.tsx # Main analyzer page
├── components/ # React components
│ ├── ui/ # shadcn/ui components
│ ├── analysis-result.tsx # Markdown report renderer
│ └── url-analyzer.tsx # URL input component
├── lib/ # Utilities and helpers
│ ├── analyze.ts # JinaAI & OpenAI integration
│ └── utils.ts # General utilities
├── hooks/ # Custom React hooks
├── types/ # TypeScript type definitions
├── documentation/ # Project documentation
└── supabase/ # Database config & migrations
```

## Documentation Setup
## 🔧 Development

To implement the generated documentation from CodeGuide:
### Available Scripts

1. Create a `documentation` folder in the root directory:
```bash
mkdir documentation
```
```bash
npm run dev # Start development server
npm run build # Build for production
npm run start # Start production server
npm run lint # Run ESLint
```

2. Place all generated markdown files from CodeGuide in this directory:
```bash
# Example structure
documentation/
├── project_requirements_document.md
├── app_flow_document.md
├── frontend_guideline_document.md
└── backend_structure_document.md
```
### Adding New Features

1. **API Routes**: Add new endpoints in `app/api/`
2. **Components**: Create reusable components in `components/`
3. **AI Integration**: Extend `lib/analyze.ts` for new AI features
4. **Styling**: Use Tailwind classes with shadcn/ui components

## 🚀 Usage

1. **Sign In**: Create an account or log in with Clerk authentication
2. **Enter URL**: Paste any webpage URL in the input field
3. **Analyze**: Click analyze and wait for AI-powered insights
4. **Review**: Read the detailed analysis with improvement suggestions
5. **Download**: Save the report as a Markdown file
6. **History**: Access previous analyses from your report history

## 📊 Performance

- **Analysis Time**: ~5-10 seconds average
- **Supported URLs**: Any publicly accessible webpage
- **Report Storage**: Local browser storage (up to ~5MB)
- **Concurrent Users**: Scalable serverless architecture

## 🛡️ Security Features

- 🔐 Secure API key storage (server-side only)
- 🔒 HTTPS enforcement
- 🧹 XSS protection with sanitized Markdown
- ⚡ Rate limiting on API endpoints
- 🛠 Input validation with Zod schemas

## 📖 API Documentation

### POST `/api/analyze`

Analyzes a webpage and returns improvement suggestions.

```typescript
// Request
{
url: string // The webpage URL to analyze
}

// Response
{
analysis: string // Markdown-formatted analysis report
}
```

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 License

3. These documentation files will be automatically tracked by git and can be used as a reference for your project's features and implementation details.
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing
## 🙏 Acknowledgments

Contributions are welcome! Please feel free to submit a Pull Request.
- [JinaAI](https://jina.ai/) for content extraction
- [OpenAI](https://openai.com/) for intelligent analysis
- [Vercel](https://vercel.com/) for seamless deployment
- [shadcn/ui](https://ui.shadcn.com/) for beautiful components
9 changes: 9 additions & 0 deletions documentation/app_flowchart.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
flowchart TD
A[User Opens App] --> B[Clerk Auth Gate]
B --> C[URL Submission Form]
C --> D[POST to api analyze]
D --> E[JinaAI Fetch Content]
E --> F[OpenAI Analyze Content]
F --> G[API Returns Markdown]
G --> H[Render AnalysisResult]
H --> I[Download Markdown Report]
Loading