Skip to content

docs: update project documentation and add Claude Code narrative #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 7, 2025
Merged

docs: update project documentation and add Claude Code narrative #112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
114 changes: 43 additions & 71 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,44 +8,20 @@ GhostPaste is a zero-knowledge encrypted code sharing platform. See `docs/SPEC.m

**Domain:** ghostpaste.dev

## Key Implementation Notes
## Project Structure

### File Structure
See the project README.md for file structure. Key directories:

```
app/ # Next.js app router pages
├── api/ # API routes
├── create/ # Gist creation page
├── g/[id]/ # Gist viewing page
└── demo/ # Demo pages for components

components/ # React components (using shadcn/ui)
├── ui/ # Reusable UI components
│ ├── code-editor.tsx # CodeMirror wrapper
│ ├── file-editor.tsx # Single file editor
│ ├── multi-file-editor.tsx # Multi-file container
│ └── copy-button.tsx # Copy functionality
├── header.tsx # App header with nav
├── share-dialog.tsx # Share URL dialog
├── gist-viewer.tsx # Read-only viewer
└── error-boundary.tsx # Error handling

lib/ # Utilities and core logic
├── crypto.ts # Encryption/decryption utilities
├── binary.ts # Binary format encoding/decoding
├── auth.ts # PIN authentication
├── copy-to-clipboard.ts # Copy utilities
├── validation.ts # Input validation
└── language-detection.ts # File type detection

types/ # TypeScript interfaces
├── models.ts # Core data models
├── api.ts # API types
└── errors.ts # Error types
```
- `app/` - Next.js app router pages
- `components/` - React components (using shadcn/ui)
- `lib/` - Utilities and core logic
- `types/` - TypeScript interfaces
- `docs/` - Project documentation

### Critical Security Rules

See `docs/SECURITY.md` for detailed security guidelines. Key rules:

1. **NEVER** send encryption keys to the server
2. **NEVER** log or store decryption keys
3. **ALWAYS** use URL fragments for key sharing (`#key=...`)
Expand All @@ -66,17 +42,9 @@ npm run deploy # Deploy to production

For more commands, see the [Local Development Guide](docs/LOCAL_DEVELOPMENT.md).

### Testing Checklist
### Testing

- [x] Encryption/decryption works correctly
- [x] Binary format encoding/decoding
- [x] PIN authentication flow
- [x] File size limits enforced
- [ ] Self-expiring gists delete properly
- [ ] One-time view gists delete after viewing
- [x] Copy-to-clipboard functionality
- [x] Toast notifications
- [x] Error boundaries contain errors properly
For testing requirements and checklist, see `docs/TODO.md` testing sections.

### Environment Variables

Expand All @@ -85,14 +53,12 @@ See `.env.example` for required Cloudflare R2 configuration.
## When Making Changes

1. **Read the spec first**: Always check `docs/SPEC.md` for requirements
2. **Test encryption**: Any crypto changes need thorough testing
3. **Check limits**: Enforce size limits (500KB/file, 5MB/gist, 20 files)
2. **Test encryption**: Any crypto changes need thorough testing (see `docs/ENCRYPTION.md`)
3. **Check limits**: Enforce size limits per `docs/SPEC.md` (500KB/file, 5MB/gist, 20 files)
4. **Validate inputs**: Especially for user-provided content
5. **Handle errors**: Provide clear error messages to users
6. **Follow guidelines**: See `CONTRIBUTING.md` for development workflow

For detailed architecture, API specs, and data models, refer to `docs/SPEC.md`.

## Git Workflow

- Always create a new branch for features/fixes
Expand Down Expand Up @@ -238,38 +204,44 @@ gh project item-edit --project-id PVT_kwHOAAF1rM4A6v2O --id [ITEM_ID] \
- [ ] After merge: Set both issue and PR to "Done"
- [ ] Update TODO.md to check off completed tasks

## Recent Accomplishments (Phase 4 UI Components)

As of June 6, 2025, we've completed 11 out of 19 Phase 4 UI components (58%):

### Completed Components

- **Critical Components** (3/3): CodeEditor, FileEditor, MultiFileEditor
- **High Priority** (6/6): Header, GistViewer, ShareDialog, ErrorBoundary, Copy to Clipboard, Design Tokens
- **Medium Priority** (2/7): AddFileButton, Toast Notifications

### Key Features Implemented
## Development Status

- Full CodeMirror 6 integration with syntax highlighting
- Multi-file editing with GitHub Gist-style UI
- Comprehensive copy-to-clipboard system with fallbacks
- Toast notifications using Sonner
- Error boundaries for graceful error handling
- Share dialog with security warnings
- Responsive header with theme toggle
For current development status and progress:

### Next Priority Components

1. Container (MEDIUM) - Layout consistency
2. ExpirySelector (MEDIUM) - Gist expiration options
3. PINInput (MEDIUM) - Security feature for edits
- **Phase Tracking**: See `docs/PHASE_*_ISSUE_TRACKING.md` files
- **TODO List**: See `docs/TODO.md` for complete task list
- **Completed Components**: See Phase 4 tracking document for UI component status

## Date Tracking

**IMPORTANT**: Always check the current date before updating documents:

```bash
date # Check current date/time
date +%Y-%m-%d # Get date in YYYY-MM-DD format
```

Last Updated: 2025-06-06
When updating any tracking documents (TODO.md, PHASE\_\*\_ISSUE_TRACKING.md, etc.), always update the "Last Updated" field to the current date.

## Key Documentation References

### Core Documentation

- **Project Specification**: `docs/SPEC.md` - Complete API and data model specifications
- **Security Guidelines**: `docs/SECURITY.md` - Security best practices and requirements
- **Encryption Details**: `docs/ENCRYPTION.md` - Encryption implementation details
- **Local Development**: `docs/LOCAL_DEVELOPMENT.md` - Development setup and workflow

### Infrastructure

- **R2 Storage**: `docs/R2_SETUP.md` - Cloudflare R2 configuration and usage
- **Dependencies**: `docs/DEPENDENCIES.md` - Package dependencies and rationale
- **Design Tokens**: `docs/DESIGN_TOKENS.md` - UI design system

### Project Management

- **TODO List**: `docs/TODO.md` - Complete task list with progress tracking
- **Phase Tracking**: `docs/PHASE_*_ISSUE_TRACKING.md` - Development phase status
- **Labels Guide**: `docs/LABELS.md` - GitHub label system documentation

Last Updated: 2025-06-07
119 changes: 107 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,26 +12,41 @@ GhostPaste is a privacy-focused code sharing platform that ensures your code sni

- **🔒 Zero-Knowledge Encryption** - Your code is encrypted locally using AES-GCM before leaving your browser
- **👤 No Account Required** - Share code instantly without signing up
- **✏️ PIN-Protected Editing** - Set a PIN to allow editing your snippets later
- **⏱️ Self-Expiring Content** - Set snippets to auto-delete after a specified time
- **👁️ One-Time View** - Create snippets that disappear after being viewed once
- **📝 Version History** - Track changes with automatic versioning
- **✏️ Password-Protected Editing** - Set a password to allow editing your snippets later
- **📝 Multi-File Support** - Share multiple files in a single gist
- **🎨 Syntax Highlighting** - Beautiful code display with CodeMirror 6
- **📋 One-Click Copy** - Copy code or share links instantly
- **🌓 Dark/Light Mode** - Easy on the eyes, day or night
- **⌨️ Keyboard Shortcuts** - Power user friendly with full keyboard support
- **📱 Responsive Design** - Works perfectly on all devices
- **🚀 Global Edge Deployment** - Fast access from anywhere in the world

### 🚧 Coming Soon

- **⏱️ Self-Expiring Content** - Set snippets to auto-delete after a specified time
- **👁️ One-Time View** - Create snippets that disappear after being viewed once
- **📝 Version History** - Track changes with automatic versioning (storage ready)

## 🚀 Quick Start

### Sharing Code

1. Visit [ghostpaste.dev](https://ghostpaste.dev)
2. Paste or write your code
3. Add multiple files if needed
4. Set optional expiration or PIN
5. Click "Create" and share the generated link
3. Add multiple files if needed (click "Add File")
4. Set an optional password for editing
5. Click "Create Gist" and share the generated link

### Viewing Shared Code

Simply open the shared link - the decryption key is in the URL fragment and never sent to our servers.
Simply open the shared link - the decryption key is in the URL fragment (#key=...) and never sent to our servers.

### Keyboard Shortcuts

- `Cmd/Ctrl + S` - Save gist
- `Cmd/Ctrl + Enter` - Create/update gist
- `Cmd/Ctrl + ?` - Show all shortcuts
- `Escape` - Close dialogs

## 🛡️ Security & Privacy

Expand All @@ -42,12 +57,14 @@ Simply open the shared link - the decryption key is in the URL fragment and neve

## 🛠️ Technical Stack

- **Framework**: Next.js 15 with React
- **Framework**: Next.js 15 with React 19
- **Runtime**: Cloudflare Workers (Edge)
- **UI Components**: shadcn/ui
- **UI Components**: shadcn/ui with Radix UI
- **Code Editor**: CodeMirror 6
- **Encryption**: Web Crypto API (AES-GCM)
- **Storage**: Cloudflare R2 with native bindings
- **Storage**: Cloudflare R2 with versioning
- **Styling**: Tailwind CSS with CSS variables
- **Testing**: Vitest with React Testing Library

## 📊 Limits

Expand All @@ -58,6 +75,28 @@ Simply open the shared link - the decryption key is in the URL fragment and neve
| Files per paste | 20 | Keeps the UI responsive |
| Versions kept | 50 | Balances history with storage |

## 📁 Project Structure

```
ghostpaste/
├── app/ # Next.js app router
│ ├── api/ # API routes
│ ├── create/ # Gist creation page
│ ├── g/[id]/ # Gist viewing page
│ └── demo/ # Component demos
├── components/ # React components
│ ├── ui/ # Reusable UI components
│ └── *.tsx # Feature components
├── lib/ # Core utilities
│ ├── storage.ts # R2 storage client
│ ├── crypto.ts # Encryption utilities
│ ├── binary.ts # Binary encoding
│ └── ... # Other utilities
├── types/ # TypeScript types
├── docs/ # Documentation
└── public/ # Static assets
```

## 🔧 Development

### Prerequisites
Expand Down Expand Up @@ -116,6 +155,36 @@ npm run build
npm run deploy
```

## 📈 Development Status

GhostPaste is actively being developed. Here's what's completed and what's in progress:

### ✅ Completed

- Core encryption/decryption system
- Multi-file editor with syntax highlighting
- Password-protected editing
- Responsive UI with dark/light mode
- Copy-to-clipboard functionality
- Keyboard shortcuts
- Error handling and boundaries
- R2 storage with versioning support
- 100% of UI components (Phase 4)

### 🚧 In Progress

- API endpoints (Phase 5 - Storage foundation complete)
- Self-expiring gists
- One-time view functionality
- Version history UI

### 📅 Upcoming

- Full API implementation
- Deployment to production
- Performance optimizations
- Additional features based on user feedback

## 📖 Documentation

- [Technical Specification](docs/SPEC.md) - Detailed architecture and implementation details
Expand All @@ -125,6 +194,7 @@ npm run deploy
- [Implementation TODO](docs/TODO.md) - Development roadmap and progress tracking
- [Contributing Guide](CONTRIBUTING.md) - How to contribute to the project
- [Local Development](docs/LOCAL_DEVELOPMENT.md) - Setting up your development environment
- [Phase Tracking](docs/PHASE_5_ISSUE_TRACKING.md) - Current development phase status

## 🤝 Contributing

Expand All @@ -147,10 +217,35 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
- Code editing powered by [CodeMirror](https://codemirror.net/)
- Hosted on [Cloudflare](https://www.cloudflare.com/)

## 🤖 Built with Claude Code

GhostPaste is a testament to the power of AI-assisted development. This entire project was built through a collaborative dialogue between human creativity and Claude's technical expertise. From architecture decisions to implementation details, every line of code emerged from thoughtful conversation.

### The Collaboration Story

What started as an idea for a privacy-focused code sharing platform evolved through hundreds of interactions with Claude Code. Together, we:

- **Architected** a zero-knowledge encryption system that keeps data private
- **Designed** a clean, intuitive UI using modern React patterns
- **Implemented** edge-compatible code for global performance
- **Solved** complex challenges like versioning and binary encoding
- **Refined** the user experience through iterative improvements

This project demonstrates that AI can be more than just a coding assistant - it can be a true development partner that helps bring ideas to life while maintaining high standards for security, performance, and user experience.

### Key Achievements

- **100% AI-Paired Development**: Every component built through human-AI collaboration
- **Production-Ready Code**: Comprehensive testing, error handling, and documentation
- **Security-First Design**: Encryption implementation guided by best practices
- **Modern Architecture**: Leveraging cutting-edge web technologies

---

<p align="center">
Made with ❤️ by <a href="https://github.com/nullcoder">Thanan Traiongthawon</a>
<strong>A collaborative creation</strong><br>
Built through the synergy of human vision and AI capability<br>
<em>Powered by Claude Code + Human Creativity</em>
</p>

<p align="center">
Expand Down
Loading