feat: create project folder structure (#23)

nullcoder · claude · web-flow · commit 658403762e5a · 2025-06-05T03:11:29.000-07:00
* feat: create project folder structure - Added app router page structure with /create and /g/[id] routes - Created placeholder pages for viewing and creating gists - Added README files for all main directories explaining conventions - Created types directory for TypeScript interfaces - Updated TODO.md to mark completed tasks 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: make dynamic route page async for Next.js 15 compatibility - Convert ViewGistPage to async function - Await params Promise as required in Next.js 15 - Add gist ID display for testing - This prepares the component for future async operations like fetching gist data 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/app/README.md b/app/README.md
@@ -0,0 +1,32 @@
+# App Directory
+
+This directory contains the Next.js 15 App Router pages and routes.
+
+## Structure
+
+```
+app/
+├── layout.tsx       # Root layout with providers
+├── page.tsx         # Home page (/)
+├── globals.css      # Global styles and Tailwind imports
+├── create/
+│   └── page.tsx     # Create new gist page (/create)
+├── g/
+│   └── [id]/
+│       └── page.tsx # View gist page (/g/[id])
+└── api/             # API routes (will be added in Phase 5)
+```
+
+## Conventions
+
+- All pages use `export default` for the page component
+- Dynamic route parameters use `params: Promise<{ paramName: string }>` in Next.js 15
+- All routes are configured for edge runtime compatibility
+- Use async components where needed for data fetching
+- Follow the colocation pattern for route-specific components
+
+## Route Overview
+
+- `/` - Landing page with create gist form
+- `/create` - Dedicated page for creating new gists (alternative to home)
+- `/g/[id]` - View a specific gist by ID (requires decryption key in URL fragment)
diff --git a/app/create/page.tsx b/app/create/page.tsx
@@ -0,0 +1,10 @@
+export default function CreateGistPage() {
+  return (
+    <div className="container mx-auto py-8">
+      <h1 className="mb-4 text-2xl font-bold">Create New Gist</h1>
+      <p className="text-muted-foreground">
+        This page will contain the form for creating encrypted gists.
+      </p>
+    </div>
+  );
+}
diff --git a/app/g/[id]/page.tsx b/app/g/[id]/page.tsx
@@ -0,0 +1,17 @@
+export default async function ViewGistPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+
+  return (
+    <div className="container mx-auto py-8">
+      <h1 className="mb-4 text-2xl font-bold">View Gist</h1>
+      <p className="text-muted-foreground">
+        This page will display the gist viewer for viewing encrypted gists.
+      </p>
+      <p className="text-muted-foreground mt-2 text-sm">Gist ID: {id}</p>
+    </div>
+  );
+}
diff --git a/components/README.md b/components/README.md
@@ -0,0 +1,52 @@
+# Components Directory
+
+This directory contains all React components used throughout the application.
+
+## Structure
+
+```
+components/
+├── ui/              # shadcn/ui components (auto-generated)
+├── theme-provider.tsx
+├── theme-toggle.tsx
+└── [future components will be added here]
+```
+
+## Conventions
+
+- All components are written in TypeScript with proper type definitions
+- Components use the `.tsx` extension
+- Follow the single responsibility principle - each component has one clear purpose
+- Use `"use client"` directive only when necessary (client-side interactivity)
+- Prefer composition over inheritance
+- Export components as named exports (except for pages)
+
+## Component Categories (to be implemented)
+
+### Layout Components
+
+- Header - Main navigation
+- Footer - Site information
+- Container - Consistent spacing wrapper
+
+### Form Components
+
+- FileTab - Multi-file support
+- CodeEditor - CodeMirror wrapper
+- ExpirySelector - Expiration time picker
+- PINInput - Secure PIN entry
+- ShareDialog - Share link with copy
+
+### Display Components
+
+- GistViewer - Display encrypted gists
+- FileList - List of files in a gist
+- LoadingStates - Loading indicators
+- ErrorBoundary - Error handling
+
+## Styling
+
+- Use Tailwind CSS classes via `cn()` utility
+- Follow shadcn/ui patterns for consistency
+- Support both light and dark themes
+- Ensure responsive design
diff --git a/docs/TODO.md b/docs/TODO.md
@@ -30,8 +30,8 @@ This document tracks the implementation progress of GhostPaste. Check off tasks
 
 ### Project Structure
 
-- [ ] Create folder structure (`app/`, `components/`, `lib/`, `types/`) - [#11](https://github.com/nullcoder/ghostpaste/issues/11)
-- [ ] Set up app router pages structure - [#11](https://github.com/nullcoder/ghostpaste/issues/11)
+- [x] Create folder structure (`app/`, `components/`, `lib/`, `types/`) - [#11](https://github.com/nullcoder/ghostpaste/issues/11)
+- [x] Set up app router pages structure - [#11](https://github.com/nullcoder/ghostpaste/issues/11)
 - [x] Create base layout with theme provider - [#8](https://github.com/nullcoder/ghostpaste/issues/8)
 - [x] Set up global styles and CSS variables - [#8](https://github.com/nullcoder/ghostpaste/issues/8)
 - [ ] Verify Cloudflare R2 setup - [#12](https://github.com/nullcoder/ghostpaste/issues/12)
diff --git a/lib/README.md b/lib/README.md
@@ -0,0 +1,46 @@
+# Lib Directory
+
+This directory contains utility functions, business logic, and service modules.
+
+## Structure
+
+```
+lib/
+├── utils.ts         # General utility functions (cn, etc.)
+└── [future modules will be added here]
+```
+
+## Planned Modules (to be implemented)
+
+### Core Modules
+
+- `crypto.ts` - Encryption/decryption utilities using Web Crypto API
+- `storage.ts` - Cloudflare R2 storage client wrapper
+- `binary.ts` - Binary format encoding/decoding for file storage
+- `auth.ts` - PIN hashing and validation
+
+### Utilities
+
+- `logger.ts` - Structured logging utility
+- `errors.ts` - Custom error classes and handling
+- `validation.ts` - Input validation helpers
+- `constants.ts` - Application constants and limits
+
+## Conventions
+
+- All modules must be edge runtime compatible (no Node.js APIs)
+- Use Web Crypto API for cryptographic operations
+- Export functions and constants as named exports
+- Write pure functions where possible
+- Include comprehensive error handling
+- Add JSDoc comments for public APIs
+
+## Edge Runtime Compatibility
+
+All code in this directory must work in Cloudflare Workers:
+
+- No `fs`, `path`, or other Node.js modules
+- Use Web APIs (fetch, crypto, etc.)
+- Keep bundle sizes small
+- Consider CPU time limits (50ms)
+- Handle streaming for large data
diff --git a/types/README.md b/types/README.md
@@ -0,0 +1,46 @@
+# Types Directory
+
+This directory contains TypeScript type definitions and interfaces used throughout the application.
+
+## Structure
+
+```
+types/
+├── index.ts         # Main export file for all types
+└── [type files will be added here]
+```
+
+## Planned Type Definitions (to be implemented)
+
+### Data Models
+
+- `GistMetadata` - Metadata stored in R2 (unencrypted)
+- `EncryptedData` - Structure of encrypted blob data
+- `UserMetadata` - User-related metadata
+
+### API Types
+
+- `APIResponse` - Standardized API response format
+- `APIError` - Error response structure
+- Request/Response types for each endpoint
+
+### Application Types
+
+- `File` - Individual file in a gist
+- `GistOptions` - Creation options (expiry, PIN, etc.)
+- `BinaryFormat` - Binary encoding format structure
+
+## Conventions
+
+- Use `interface` for object shapes
+- Use `type` for unions, aliases, and complex types
+- Export all types from `index.ts` for easy imports
+- Prefix enum values with the enum name
+- Document complex types with JSDoc comments
+- Avoid using `any` - use `unknown` if type is truly unknown
+
+## Example Import
+
+```typescript
+import { GistMetadata, APIResponse } from "@/types";
+```
