|
| 1 | +# ByteBox - Project Structure |
| 2 | + |
| 3 | +## Directory Organization |
| 4 | + |
| 5 | +``` |
| 6 | +ByteBox/ |
| 7 | +├── src/ # Application source code |
| 8 | +│ ├── app/ # Next.js App Router pages and API routes |
| 9 | +│ │ ├── api/ # Backend API endpoints |
| 10 | +│ │ ├── search/ # Search page with filters |
| 11 | +│ │ ├── settings/ # Settings/appearance page |
| 12 | +│ │ ├── tags/ # Tag directory page |
| 13 | +│ │ ├── globals.css # Global styles with Tailwind + glass/theming tokens |
| 14 | +│ │ ├── layout.tsx # Root layout with ThemeProvider |
| 15 | +│ │ └── page.tsx # Main dashboard (boards) |
| 16 | +│ ├── components/ # React components |
| 17 | +│ │ ├── cards/ # Card-related components |
| 18 | +│ │ ├── layout/ # Layout components (AppLayout, Board, CategoryColumn) |
| 19 | +│ │ └── ui/ # Reusable UI components |
| 20 | +│ ├── contexts/ # React Context providers |
| 21 | +│ │ └── ThemeContext.tsx # Theme, accent, icon, and wallpaper controller |
| 22 | +│ ├── hooks/ # Custom React hooks |
| 23 | +│ │ └── useSearch.ts # Search & filter hook |
| 24 | +│ ├── lib/ # Utility libraries |
| 25 | +│ │ ├── db/ # Prisma client & database queries |
| 26 | +│ │ ├── utils/ # Helper functions (cn, generateId, formatDate, etc.) |
| 27 | +│ │ └── themeRegistry.ts # Accent & icon palette definitions |
| 28 | +│ └── types/ # TypeScript type definitions |
| 29 | +│ ├── index.ts # Main type definitions |
| 30 | +│ └── indev.ts # Development/experimental types |
| 31 | +├── prisma/ # Database configuration |
| 32 | +│ ├── migrations/ # Database migration history |
| 33 | +│ ├── schema.prisma # Database schema definition |
| 34 | +│ ├── seed.ts # Database seed script |
| 35 | +│ └── dev.db # SQLite database file |
| 36 | +├── public/ # Static assets |
| 37 | +│ ├── wallpapers/ # Built-in wallpaper images |
| 38 | +│ ├── favicon.png # Site favicon |
| 39 | +│ ├── icon.png # App icon |
| 40 | +│ └── logo_banner.png # Logo asset |
| 41 | +├── scripts/ # Build and utility scripts |
| 42 | +│ └── next-with-env.cjs # Environment-aware Next.js wrapper |
| 43 | +├── .amazonq/ # Amazon Q configuration |
| 44 | +│ └── rules/ # Project rules and documentation |
| 45 | +│ └── memory-bank/ # Memory Bank documentation |
| 46 | +├── DEV/ # Development resources and backups |
| 47 | +├── .next/ # Next.js build output (generated) |
| 48 | +└── node_modules/ # Dependencies (generated) |
| 49 | +``` |
| 50 | + |
| 51 | +## Core Components |
| 52 | + |
| 53 | +### Application Layer (`src/app/`) |
| 54 | + |
| 55 | +#### Pages |
| 56 | +- **page.tsx** — Main dashboard with kanban boards, drag-and-drop, and card management |
| 57 | +- **search/page.tsx** — Dedicated search experience with advanced filtering |
| 58 | +- **settings/page.tsx** — Appearance customization, data management, and about section |
| 59 | +- **tags/page.tsx** — Tag directory with statistics and filtering capabilities |
| 60 | +- **layout.tsx** — Root layout wrapping all pages with ThemeProvider and global styles |
| 61 | + |
| 62 | +#### API Routes (`src/app/api/`) |
| 63 | +- **cards/** — CRUD operations for cards (create, read, update, delete) |
| 64 | +- **categories/** — Category management endpoints |
| 65 | +- **tags/** — Tag management and filtering |
| 66 | +- **export/** — Data export to JSON |
| 67 | +- **import/** — Data import from JSON |
| 68 | +- **settings/** — User settings persistence |
| 69 | + |
| 70 | +### Component Layer (`src/components/`) |
| 71 | + |
| 72 | +#### Cards (`components/cards/`) |
| 73 | +- **Card.tsx** — Base card component with type-specific rendering |
| 74 | +- **DraggableCard.tsx** — Wrapper adding drag-and-drop functionality |
| 75 | +- **CardModal.tsx** — Full-screen modal for viewing/editing cards |
| 76 | +- **CreateCardModal.tsx** — Modal for creating new cards with type selection |
| 77 | +- **ImageCard.tsx** — Specialized component for image cards with lightbox |
| 78 | + |
| 79 | +#### Layout (`components/layout/`) |
| 80 | +- **AppLayout.tsx** — Main application shell with sidebar, header, and content area |
| 81 | +- **Board.tsx** — Kanban board container managing categories and drag-and-drop |
| 82 | +- **CategoryColumn.tsx** — Individual category column with cards |
| 83 | +- **Sidebar.tsx** — Navigation sidebar with filters and actions |
| 84 | +- **Header.tsx** — Top header with search, view modes, and theme toggle |
| 85 | + |
| 86 | +#### UI (`components/ui/`) |
| 87 | +- **Tag.tsx** — Tag display and interaction component |
| 88 | +- **SearchBar.tsx** — Global search with keyboard shortcuts |
| 89 | +- **FilterPanel.tsx** — Advanced filtering UI (tags, starred, date) |
| 90 | +- **CodeBlock.tsx** — Syntax-highlighted code display with copy button |
| 91 | +- **ThemeToggle.tsx** — Light/dark mode switcher |
| 92 | +- **ExportImport.tsx** — Data backup and restore UI |
| 93 | +- **Button.tsx** — Reusable button component with variants |
| 94 | +- **Modal.tsx** — Base modal component with glass styling |
| 95 | + |
| 96 | +### Context & State (`src/contexts/`) |
| 97 | + |
| 98 | +#### ThemeContext.tsx |
| 99 | +Central theme management providing: |
| 100 | +- Light/dark mode state |
| 101 | +- Accent theme selection and custom palette creation |
| 102 | +- Icon theme/color management |
| 103 | +- Background configuration (solid, gradient, wallpaper, upload) |
| 104 | +- Font selection (UI and mono fonts) |
| 105 | +- Glass intensity control |
| 106 | +- Settings presets (save/load/delete) |
| 107 | +- Persistence to database via API |
| 108 | + |
| 109 | +### Hooks (`src/hooks/`) |
| 110 | + |
| 111 | +#### useSearch.ts |
| 112 | +Provides search and filtering functionality: |
| 113 | +- Full-text search across cards |
| 114 | +- Tag filtering with AND/OR logic |
| 115 | +- Starred filter |
| 116 | +- Date range filtering |
| 117 | +- View mode management (all, recent, starred, by-tag) |
| 118 | +- Debounced search for performance |
| 119 | + |
| 120 | +### Library Layer (`src/lib/`) |
| 121 | + |
| 122 | +#### Database (`lib/db/`) |
| 123 | +- **client.ts** — Prisma client singleton |
| 124 | +- **queries.ts** — Reusable database query functions |
| 125 | +- **seed.ts** — Database seeding utilities |
| 126 | + |
| 127 | +#### Utils (`lib/utils/`) |
| 128 | +- **cn.ts** — Class name merging utility (clsx + tailwind-merge) |
| 129 | +- **generateId.ts** — Unique ID generation |
| 130 | +- **formatDate.ts** — Date formatting helpers |
| 131 | +- **truncate.ts** — Text truncation utility |
| 132 | +- **syntax.ts** — Syntax highlighting configuration (Shiki) |
| 133 | +- **imageUtils.ts** — Image compression and processing |
| 134 | + |
| 135 | +#### Theme Registry (`lib/themeRegistry.ts`) |
| 136 | +Defines: |
| 137 | +- Built-in accent themes (Byte Classic, Neon Night, etc.) |
| 138 | +- Icon palettes (Neon Grid, Carbon Tech, etc.) |
| 139 | +- Gradient presets |
| 140 | +- Wallpaper library |
| 141 | +- Font stacks (UI and mono) |
| 142 | + |
| 143 | +### Type Definitions (`src/types/`) |
| 144 | + |
| 145 | +#### index.ts |
| 146 | +Core types: |
| 147 | +- **Card** — Card data structure with all fields |
| 148 | +- **Category** — Category/board structure |
| 149 | +- **Tag** — Tag structure with color |
| 150 | +- **CardType** — Union type for card types |
| 151 | +- **ViewMode** — View mode options |
| 152 | +- **FilterState** — Filter configuration |
| 153 | +- **ThemeMode** — Light/dark mode |
| 154 | +- **AccentTheme** — Accent color palette structure |
| 155 | +- **IconTheme** — Icon color configuration |
| 156 | +- **BackgroundConfig** — Background settings |
| 157 | +- **FontConfig** — Font selection |
| 158 | +- **SettingsPreset** — Saved appearance preset |
| 159 | + |
| 160 | +## Database Schema |
| 161 | + |
| 162 | +### Models (Prisma) |
| 163 | + |
| 164 | +#### Category |
| 165 | +- Represents boards/columns in the UI |
| 166 | +- Fields: id, name, description, color, order, cards[], createdAt, updatedAt |
| 167 | +- Default color: #ec4899 (Pink Pixel brand) |
| 168 | + |
| 169 | +#### Tag |
| 170 | +- For organizing and filtering cards |
| 171 | +- Fields: id, name (unique), color, cards[], createdAt, updatedAt |
| 172 | +- Default color: #8b5cf6 (Purple brand) |
| 173 | + |
| 174 | +#### Card |
| 175 | +- Main content type (bookmarks, snippets, commands, docs, images) |
| 176 | +- Fields: id, type, title, description, content, imageData, fileData, fileName, fileType, fileSize, language, starred, categoryId, category, tags[], order, createdAt, updatedAt |
| 177 | +- Indexed by: categoryId, type |
| 178 | +- Cascade delete with category |
| 179 | + |
| 180 | +#### UserSettings |
| 181 | +- Singleton pattern (id always "default") |
| 182 | +- Fields: id, mode, accentThemeId, iconThemeId, customIconColor, glassIntensity, backgroundConfig (JSON), fontConfig (JSON), customAccentThemes (JSON), settingsPresets (JSON), createdAt, updatedAt |
| 183 | +- Stores all theme and appearance preferences |
| 184 | + |
| 185 | +## Architectural Patterns |
| 186 | + |
| 187 | +### Next.js App Router |
| 188 | +- Server Components by default for optimal performance |
| 189 | +- Client Components marked with 'use client' directive |
| 190 | +- API routes in app/api/ directory |
| 191 | +- File-based routing |
| 192 | + |
| 193 | +### Component Composition |
| 194 | +- Small, focused components with single responsibility |
| 195 | +- Composition over inheritance |
| 196 | +- Props drilling minimized via Context API |
| 197 | +- Reusable UI components in components/ui/ |
| 198 | + |
| 199 | +### State Management |
| 200 | +- React Context for global state (theme, settings) |
| 201 | +- Local state with useState for component-specific data |
| 202 | +- Server state managed via API routes and database |
| 203 | + |
| 204 | +### Styling Architecture |
| 205 | +- Tailwind CSS utility classes |
| 206 | +- CSS custom properties for theming (--accent-*, --glass-*) |
| 207 | +- Glass utilities in globals.css |
| 208 | +- Component-scoped styles when needed |
| 209 | + |
| 210 | +### Data Flow |
| 211 | +1. User interaction → Component |
| 212 | +2. Component → API route (fetch/POST) |
| 213 | +3. API route → Prisma query |
| 214 | +4. Prisma → SQLite database |
| 215 | +5. Response → Component state update |
| 216 | +6. Re-render with new data |
| 217 | + |
| 218 | +### Drag & Drop Architecture |
| 219 | +- @dnd-kit library for drag-and-drop |
| 220 | +- DndContext wraps draggable areas |
| 221 | +- Sensors for mouse, touch, and keyboard |
| 222 | +- Collision detection algorithms |
| 223 | +- onDragEnd handler updates database |
| 224 | + |
| 225 | +### Search & Filter Architecture |
| 226 | +- useSearch hook centralizes logic |
| 227 | +- Debounced search input (300ms) |
| 228 | +- Client-side filtering for instant results |
| 229 | +- Tag filtering with AND/OR logic |
| 230 | +- View modes control data display |
| 231 | + |
| 232 | +## Configuration Files |
| 233 | + |
| 234 | +- **package.json** — Dependencies and scripts |
| 235 | +- **tsconfig.json** — TypeScript configuration |
| 236 | +- **next.config.ts** — Next.js configuration |
| 237 | +- **tailwind.config.ts** — Tailwind CSS configuration |
| 238 | +- **postcss.config.mjs** — PostCSS configuration |
| 239 | +- **prisma.config.ts** — Prisma configuration |
| 240 | +- **eslint.config.mjs** — ESLint rules |
| 241 | +- **.env** — Environment variables (DATABASE_URL) |
0 commit comments