From 53d9fe9eed789c337208ff88559e60f1e54eaca5 Mon Sep 17 00:00:00 2001 From: Baseline User Date: Thu, 7 May 2026 11:13:43 -0400 Subject: [PATCH 01/20] docs: add codebase map and redesign implementation plan Phase 1 & 2 of PDFaro redesign: comprehensive codebase discovery doc and implementation plan covering all screens, risk levels, component inventory, test plan, and rollback strategy. Co-Authored-By: Claude Sonnet 4.6 --- docs/PDFARO_CODEBASE_MAP.md | 332 ++++++++++++++++++++ docs/PDFARO_REDESIGN_IMPLEMENTATION_PLAN.md | 237 ++++++++++++++ 2 files changed, 569 insertions(+) create mode 100644 docs/PDFARO_CODEBASE_MAP.md create mode 100644 docs/PDFARO_REDESIGN_IMPLEMENTATION_PLAN.md diff --git a/docs/PDFARO_CODEBASE_MAP.md b/docs/PDFARO_CODEBASE_MAP.md new file mode 100644 index 000000000..38f2c9ad6 --- /dev/null +++ b/docs/PDFARO_CODEBASE_MAP.md @@ -0,0 +1,332 @@ +# PDFaro Codebase Map + +_Generated 2026-05-07 — Phase 1 discovery document for the PDFaro redesign._ + +--- + +## 1. Project Overview + +| Attribute | Value | +|-----------|-------| +| **Framework** | Next.js 15.1.8 (App Router, static export) | +| **Language** | TypeScript 5.6.3 | +| **Runtime** | React 19 | +| **Styling** | Tailwind CSS v4.0 with `@tailwindcss/postcss`, CSS custom properties (HSL-based design tokens) | +| **Build** | Next.js + Turbopack (dev) / Webpack (prod) | +| **Testing** | Vitest 2.1.3 + @testing-library/react 16 | +| **i18n** | next-intl 4.1.0 — locale routing under `/[locale]/` | +| **State** | Zustand 5 (global), React Context (tool context), custom hooks (favorites, undo/redo) | +| **PDF Engine** | pdf-lib, pdfjs-dist, qpdf-wasm, PyMuPDF-wasm, Tesseract.js (OCR), LibreOffice WASM | +| **Desktop** | Tauri v2 — static Next.js export wrapped in a native shell | +| **Main Entry Points** | `src/app/layout.tsx` → `src/app/[locale]/layout.tsx` → page components | + +--- + +## 2. Folder Structure Map + +``` +pdfcraft/ +├── src/ +│ ├── app/ # Next.js 15 App Router +│ │ ├── layout.tsx # Root layout — font setup, global CSS +│ │ ├── page.tsx # Redirect: / → /[detected-locale] +│ │ ├── global-error.tsx # Uncaught error boundary +│ │ ├── globals.css # Design tokens (CSS vars) + Tailwind import +│ │ ├── manifest.ts # PWA manifest +│ │ ├── robots.ts / sitemap.ts +│ │ └── [locale]/ # All user-facing pages under locale prefix +│ │ ├── layout.tsx # Locale layout (next-intl provider, theme, a11y) +│ │ ├── page.tsx # Homepage (server component → HomePageClient) +│ │ ├── HomePageClient.tsx +│ │ ├── error.tsx / not-found.tsx +│ │ ├── tools/ +│ │ │ ├── page.tsx +│ │ │ ├── ToolsPageClient.tsx +│ │ │ ├── [tool]/page.tsx # Individual tool server component +│ │ │ └── category/[category]/page.tsx +│ │ ├── workflow/ +│ │ │ ├── page.tsx +│ │ │ └── WorkflowPageClient.tsx +│ │ ├── about/ contact/ privacy/ faq/ # Static info pages +│ │ └── (each has page.tsx) +│ │ +│ ├── components/ +│ │ ├── ui/ # Primitive/base UI atoms +│ │ ├── layout/ # Header, Footer, Navigation, LanguageSelector, MobileMenu +│ │ ├── common/ # Shared functional components (FileUploader, GuidedTour…) +│ │ ├── tools/ # Tool UI — ToolCard, ToolGrid, ToolPage + 80+ tool-specific folders +│ │ ├── workflow/ # Workflow editor components (ReactFlow-based) +│ │ └── seo/ # JsonLd, PerformanceHints +│ │ +│ ├── lib/ +│ │ ├── pdf/ # PDF processing core (processor.ts routes operations) +│ │ │ └── processors/ # 90+ individual processor files +│ │ ├── hooks/ # PDF-related hooks (usePdfLibrary, useBatchProcessing…) +│ │ ├── contexts/ # ToolContext (current tool slug/name) +│ │ ├── storage/ # IndexedDB (projects), localStorage (recent files) +│ │ ├── workflow/ # Workflow execution engine +│ │ ├── libreoffice/ # LibreOffice WASM wrapper +│ │ ├── i18n/ # i18n config, fallback strings, RTL support +│ │ ├── seo/ # Metadata + JSON-LD generation +│ │ └── utils/ # Accessibility, logger, sanitizer, search, asset-loader +│ │ +│ ├── hooks/ # App-level hooks: useFavorites, useUndoRedo +│ ├── types/ # TypeScript definitions (pdf, tool, workflow, i18n…) +│ ├── config/ # tools.ts (tool registry), icons.ts, tool-content/ +│ ├── i18n/ # next-intl request.ts handler +│ └── __tests__/ # All test files (see §7) +│ +├── messages/ # i18n JSON message files (en, es, fr, de, pt, ja, zh, ar, hi) +├── public/ # Static assets (icons, images, WASM workers) +├── scripts/ # Build helpers (decompress-wasm, chunk-assets, sync-pdfjs-workers) +├── Redesign-figma/ # 16 PNG design mockups (light + dark per screen) +├── src-tauri/ # Tauri native shell (Rust config + assets) +├── extension/ # Browser extension code +├── next.config.js # Next.js config (static export, WASM, COEP/COOP headers) +├── postcss.config.js # Tailwind v4 via @tailwindcss/postcss +├── vitest.config.ts # Vitest setup +└── tsconfig.json +``` + +--- + +## 3. Routing Map + +All routes live under `src/app/[locale]/`. The locale is detected automatically and the user is redirected from `/` to `/`. + +| Route | File | Notes | +|-------|------|-------| +| `/` | `[locale]/page.tsx` → `HomePageClient.tsx` | Homepage with hero, popular tools, categories | +| `//tools` | `tools/page.tsx` → `ToolsPageClient.tsx` | Full tools directory with search + filter | +| `//tools/` | `tools/[tool]/page.tsx` → per-tool component | Individual tool interface | +| `//tools/category/` | `tools/category/[category]/page.tsx` | Category-filtered tool list | +| `//workflow` | `workflow/page.tsx` → `WorkflowPageClient.tsx` | ReactFlow workflow builder | +| `//about` | `about/page.tsx` | About page | +| `//faq` | `faq/page.tsx` | FAQ page | +| `//privacy` | `privacy/page.tsx` | Privacy policy | +| `//contact` | `contact/page.tsx` | Contact/feedback | + +**Locale routing:** next-intl middleware (in `src/i18n/request.ts`) detects locale from cookie/Accept-Language, falls back to `en`. Supported locales: `en, es, fr, de, pt, ja, zh, ar, hi`. + +--- + +## 4. UI Component Map + +### Base UI atoms — `src/components/ui/` +| Component | Purpose | +|-----------|---------| +| `Button.tsx` | Primary/secondary/ghost/outline/destructive variants; size sm/md/lg; loading state; forwardRef | +| `Card.tsx` | Surface container with optional hover lift effect | +| `Modal.tsx` | Dialog overlay with focus trap | +| `Tabs.tsx` | Tab strip for multi-view layouts | +| `FormField.tsx` | Label + input wrapper with error messaging | +| `ThemeToggle.tsx` | Sun/moon toggle that applies `.dark` class to `` | +| `FavoriteButton.tsx` | Star icon toggling a tool as favorite (persisted via useFavorites) | +| `OptimizedImage.tsx` | Next.js Image wrapper with loading states | + +### Layout — `src/components/layout/` +| Component | Purpose | +|-----------|---------| +| `Header.tsx` | Fixed top bar; logo, nav pill, search (Cmd+K), recent files, GitHub, theme toggle, mobile menu toggle | +| `Footer.tsx` | 4-column grid: brand/social, tool links, language selector, legal | +| `Navigation.tsx` | Desktop nav items (also used inside Header) | +| `LanguageSelector.tsx` | Dropdown to change locale; persists choice in cookie | +| `MobileMenu.tsx` | Slide-down nav for `md:` breakpoint and below | + +### Common shared — `src/components/common/` +| Component | Purpose | +|-----------|---------| +| `FileUploader.tsx` | Drag-drop + click + paste + keyboard file input; multi-file; type/size validation | +| `GuidedTour.tsx` | Onboarding tour overlay (useGuidedTour hook) | +| `BatchProcessingPanel.tsx` | UI for batch file processing | +| `SavedProjectsPanel.tsx` | Saved project browsing (IndexedDB) | +| `RecentFilesDropdown.tsx` | Recent file history from localStorage | +| `LiveRegion.tsx` | `role="status"` ARIA live region for async announcements | +| `SkipLink.tsx` | "Skip to main content" a11y link | +| `PdfLibraryLoader.tsx` | Lazy-load indicator for WASM libraries | + +### Tools — `src/components/tools/` +| Component | Purpose | +|-----------|---------| +| `ToolCard.tsx` | Card for tools directory / grid — icon, name, description, favorite, category badge | +| `ToolGrid.tsx` | Responsive grid of ToolCards | +| `ToolPage.tsx` | Full tool page shell — Header, breadcrumb, tool header, children (tool UI), related tools, Footer | +| `ProcessingProgress.tsx` | Progress bar + status text during PDF processing | +| `DownloadButton.tsx` | Download result file; triggers Blob URL download | +| `FilePreview.tsx` | PDF page thumbnail preview | +| `FavoriteToolsSection.tsx` | Section showing favorited tools on homepage | +| `/` (80+ folders) | Each tool has its own component (e.g., `compress/CompressTool.tsx`) | + +### Workflow — `src/components/workflow/` +| Component | Purpose | +|-----------|---------| +| `WorkflowEditor.tsx` | ReactFlow canvas; drag-drop nodes; zoom/pan | +| `WorkflowControls.tsx` | Run/save/undo/redo toolbar | +| `ToolNode.tsx` | Custom ReactFlow node rendering a PDF tool | +| `CustomEdge.tsx` | Animated directed edge between nodes | +| `ToolSidebar.tsx` | Left panel — categorized tool list to drag onto canvas | +| `NodeSettingsPanel.tsx` | Right panel — settings for selected node | +| `FileListPanel.tsx` | Input file list panel | +| `WorkflowLibrary.tsx` | Pre-built workflow templates | +| `WorkflowHistory.tsx` | Execution history log | +| `WorkflowPreview.tsx` | Preview modal for workflow output | + +--- + +## 5. Interaction Map + +### User opens a tool +1. User navigates to `//tools/`. +2. `tools/[tool]/page.tsx` (server) resolves tool config + localized content from `src/config/`. +3. Renders `` which includes `
`, breadcrumb, tool heading, the tool-specific child component, related tools section, and `