3486541272
* Increase coverage * Add comprehensive LLM development documentation - Add CLAUDE.md as main documentation index - Create 8 detailed documentation files in docs/: - architecture.md: Tech stack, data models, auth system - directory-structure.md: Complete file tree with paths - backend-patterns.md: Module architecture and patterns - database.md: Models, migrations, and workflows - development-workflow.md: Setup and daily development - code-conventions.md: Style guide and best practices - testing.md: Test organization and patterns - common-tasks.md: How-to guides for frequent tasks - Update .gitignore to allow project-level CLAUDE.md - 4,285 lines of comprehensive documentation - Organized for easy navigation with cross-links - LLM-optimized with absolute paths and code examples * fixup! Add comprehensive LLM development documentation
19 KiB
19 KiB
Directory Structure
Project Root
/Users/chris/c0deLab/ProjectLand/tududi/
├── README.md # User-facing documentation
├── CLAUDE.md # This developer guide (index)
├── LICENSE # MIT License
├── package.json # Root scripts and dependencies (monorepo)
├── package-lock.json # Dependency lock file
│
├── Configuration Files
├── webpack.config.js # Frontend build configuration
├── tsconfig.json # TypeScript config (frontend only)
├── jest.config.js # Jest config for frontend tests
├── babel.config.js # Babel transpilation for Jest + Webpack
├── eslint.config.mjs # ESLint flat config
├── .prettierrc.json # Prettier code formatting
├── tailwind.config.js # Tailwind CSS customization
├── .sequelizerc # Sequelize CLI configuration
├── postcss.config.js # PostCSS config for Tailwind
│
├── Docker & Deployment
├── Dockerfile # Production Docker image (multi-stage)
├── docker-compose.yml # Development Docker setup
├── .dockerignore # Docker build exclusions
│
├── Git & GitHub
├── .gitignore
├── .github/
│ ├── CONTRIBUTING.md # Contribution guidelines
│ └── workflows/ # GitHub Actions (if any)
│
├── Source Code
├── backend/ # Express backend → See Backend Structure
├── frontend/ # React frontend → See Frontend Structure
├── public/ # Static assets (fonts, locales, images)
├── dist/ # Production build output
├── e2e/ # Playwright E2E tests
├── scripts/ # Build and utility scripts
├── docs/ # Documentation (this directory)
│
└── Other
├── screenshots/ # App screenshots for README
├── uploads/ # User file uploads (not in git)
├── test-results/ # Playwright test results
└── node_modules/ # Dependencies
Backend Structure
/Users/chris/c0deLab/ProjectLand/tududi/backend/
│
├── app.js # Main Express application entry point
│ # - Middleware setup (Helmet, CORS, compression)
│ # - Session management
│ # - Rate limiting
│ # - Module registration
│ # - Swagger integration
│ # - SPA fallback routing
│
├── modules/ # Feature modules (modular architecture)
│ │
│ ├── tasks/ # Task management (MOST COMPLEX MODULE)
│ │ ├── routes.js # Express routes
│ │ ├── repository.js # Data access layer
│ │ ├── recurringTaskService.js
│ │ ├── taskEventService.js
│ │ ├── taskScheduler.js # Cron-based scheduling
│ │ ├── operations/ # Business logic operations
│ │ │ ├── list.js # List operations
│ │ │ ├── completion.js # Status changes
│ │ │ ├── recurring.js # Recurrence handling
│ │ │ ├── subtasks.js # Subtask CRUD
│ │ │ ├── tags.js # Tag assignment
│ │ │ ├── grouping.js # Grouping logic
│ │ │ ├── sorting.js # Sort orders
│ │ │ └── parent-child.js # Hierarchy ops
│ │ ├── queries/ # Query builders
│ │ │ ├── query-builders.js
│ │ │ ├── metrics-queries.js
│ │ │ └── metrics-computation.js
│ │ ├── core/ # Core utilities
│ │ │ ├── serializers.js # Format API responses
│ │ │ ├── parsers.js # Parse request data
│ │ │ ├── builders.js # Build database objects
│ │ │ └── comparators.js # Detect changes
│ │ ├── middleware/
│ │ │ └── access.js # Access control
│ │ └── utils/
│ │ ├── constants.js
│ │ ├── validation.js
│ │ └── logging.js
│ │
│ ├── projects/ # Project management
│ │ ├── routes.js
│ │ ├── repository.js
│ │ └── utils/
│ │ └── validation.js
│ │
│ ├── areas/ # Area organization
│ ├── notes/ # Notes management
│ ├── tags/ # Tag system
│ ├── users/ # User management
│ ├── auth/ # Authentication (login/register)
│ ├── shares/ # Project sharing & permissions
│ ├── telegram/ # Telegram bot integration
│ ├── inbox/ # Inbox items
│ ├── habits/ # Habit tracking
│ ├── notifications/ # Notification system
│ ├── search/ # Universal search
│ ├── views/ # Saved views
│ ├── admin/ # Admin functions
│ ├── backup/ # Backup/restore (33KB, complex)
│ ├── feature-flags/ # Feature flag management
│ ├── quotes/ # Daily quotes
│ └── url/ # URL handling
│
├── models/ # Sequelize model definitions
│ ├── index.js # Model initialization & associations
│ ├── task.js # Task model (recurrence fields)
│ ├── project.js # Project model
│ ├── area.js # Area model
│ ├── note.js # Note model
│ ├── tag.js # Tag model
│ ├── user.js # User model (bcrypt password, settings)
│ ├── permission.js # Permission/sharing model
│ ├── apiToken.js # API token model
│ ├── recurringCompletion.js
│ ├── taskEvent.js # Task audit log
│ ├── taskAttachment.js
│ ├── inboxItem.js
│ ├── notification.js
│ ├── role.js
│ ├── view.js
│ ├── backup.js
│ ├── setting.js
│ └── action.js
│
├── migrations/ # Database migrations (64+ files)
│ ├── 20240101120000-initial-schema.js
│ ├── 20240115140000-add-recurring-tasks.js
│ └── ... (timestamped migration files)
│
├── seeders/ # Database seed data
│ └── (seed files if any)
│
├── middleware/ # Global middleware
│ ├── auth.js # Authentication (session + Bearer token)
│ ├── authorize.js # Authorization (permission checking)
│ ├── rateLimiter.js # Rate limiting config (5 different limiters)
│ ├── queryLogger.js # Development query logging
│ └── permissionCache.js
│
├── services/ # Cross-cutting services
│ ├── permissionsService.js # Main permissions service
│ ├── backupService.js # Backup/restore operations
│ ├── emailService.js # Email notifications
│ ├── logService.js # Error logging
│ ├── applyPerms.js # Apply permissions
│ └── permissionsCalculators.js # Permission calculations
│
├── shared/ # Shared utilities
│ ├── errors/ # Custom error classes
│ │ ├── AppError.js
│ │ ├── NotFoundError.js
│ │ ├── ValidationError.js
│ │ ├── ConflictError.js
│ │ ├── UnauthorizedError.js
│ │ └── ForbiddenError.js
│ ├── middleware/
│ │ └── errorHandler.js # Global error handler
│ └── database/
│ └── BaseRepository.js # Base repository class
│
├── utils/ # Utility functions
│ ├── uid.js # Generate 15-char unique IDs (nanoid)
│ ├── slug-utils.js # URL slug handling, UID extraction
│ ├── timezone-utils.js # Timezone conversions, date calculations
│ ├── attachment-utils.js # File handling and validation
│ ├── migration-utils.js # Database migration helpers
│ ├── request-utils.js # Request utilities
│ └── notificationPreferences.js
│
├── config/ # Configuration
│ ├── config.js # Environment-based config
│ ├── database.js # Sequelize database config
│ └── swagger.js # Swagger API schema (30KB)
│
├── docs/ # API documentation
│ └── swagger/
│ └── (swagger doc files)
│
├── scripts/ # Utility scripts
│ └── (database management scripts)
│
└── tests/ # Backend tests
├── unit/ # Unit tests
│ ├── models/
│ │ ├── task.test.js
│ │ ├── project.test.js
│ │ ├── user.test.js
│ │ └── ...
│ ├── middleware/
│ │ ├── auth.test.js
│ │ └── authorize.test.js
│ ├── services/
│ │ ├── permissionsService.test.js
│ │ └── applyPerms.test.js
│ └── utils/
│ ├── timezone-utils.test.js
│ ├── slug-utils.test.js
│ ├── attachment-utils.test.js
│ └── migration-utils.test.js
│
└── integration/ # Integration tests (47+ test directories)
├── tasks/
│ ├── tasks.test.js
│ ├── subtasks.test.js
│ └── recurring.test.js
├── projects/
├── areas/
├── notes/
├── tags/
├── auth/
├── shares/
└── ...
Frontend Structure
/Users/chris/c0deLab/ProjectLand/tududi/frontend/
│
├── index.tsx # React application entry point
│ # - React root initialization
│ # - i18n setup
│ # - Dark mode initialization
│ # - Service worker cleanup
│
├── App.tsx # Root component (13KB)
│ # - Route definitions
│ # - User authentication check
│ # - Route protection
│ # - Layout wrapper
│
├── Layout.tsx # Main layout wrapper (21KB)
│ # - Sidebar integration
│ # - Navigation
│ # - Modal management
│
├── components/ # React components (feature-based)
│ │
│ ├── Task/ # Task-related components
│ │ ├── TasksToday.tsx
│ │ ├── TaskDetails.tsx
│ │ ├── TaskForm.tsx
│ │ ├── TaskItem.tsx
│ │ ├── TaskList.tsx
│ │ ├── TaskFilters.tsx
│ │ ├── SubtaskList.tsx
│ │ └── ...
│ │
│ ├── Project/ # Project components
│ │ ├── ProjectDetails.tsx
│ │ ├── ProjectForm.tsx
│ │ ├── ProjectList.tsx
│ │ ├── ProjectCard.tsx
│ │ └── ...
│ │
│ ├── Area/ # Area components
│ │ ├── AreaDetails.tsx
│ │ ├── AreaForm.tsx
│ │ └── ...
│ │
│ ├── Note/ # Note components
│ │ ├── NoteDetails.tsx
│ │ ├── NoteForm.tsx
│ │ └── ...
│ │
│ ├── Tag/ # Tag components
│ ├── Habits/ # Recurring tasks UI
│ ├── Inbox/ # Inbox management
│ │
│ ├── Calendar/ # Calendar view (27KB)
│ │ └── Calendar.tsx
│ │
│ ├── Sidebar.tsx # Left navigation sidebar
│ ├── Navbar.tsx # Top navigation bar
│ │
│ ├── Metrics/ # Productivity metrics
│ │ └── ...
│ │
│ ├── Notifications/ # Notification system
│ ├── UniversalSearch/ # Search interface
│ │
│ ├── Shared/ # Shared UI components (41 items)
│ │ ├── Modal components
│ │ │ ├── Modal.tsx
│ │ │ ├── ConfirmDialog.tsx
│ │ │ └── ...
│ │ ├── Form inputs
│ │ │ ├── Input.tsx
│ │ │ ├── Select.tsx
│ │ │ ├── DatePicker.tsx
│ │ │ └── ...
│ │ ├── ToastContext.tsx
│ │ ├── LoadingScreen.tsx
│ │ ├── Button.tsx
│ │ ├── Badge.tsx
│ │ └── ...
│ │
│ ├── Admin/ # Admin panel
│ ├── Backup/ # Backup/restore UI
│ ├── Profile/ # User profile settings
│ │ ├── ProfileSettings.tsx
│ │ ├── ApiTokens.tsx
│ │ └── ...
│ ├── Productivity/ # Analytics dashboard
│ └── Login/Register # Auth pages
│ ├── Login.tsx
│ └── Register.tsx
│
├── store/ # Zustand state management
│ └── useStore.ts # Global store (28KB)
│ # - Task state & cache
│ # - Project state & cache
│ # - UI state (modals, filters, selections)
│ # - Cache management functions
│
├── contexts/ # React contexts
│ ├── ModalContext.tsx # Modal state management
│ ├── SidebarContext.tsx # Sidebar state
│ └── TelegramStatusContext.tsx # Telegram integration status
│
├── hooks/ # Custom React hooks
│ ├── useKeyboardShortcuts.ts # Keyboard handling
│ ├── useModalManager.ts # Modal management
│ ├── usePersistedModal.ts # Modal persistence
│ └── useTasksData.ts # Task data fetching
│
├── utils/ # Frontend utilities (30+ files)
│ ├── API Services (API client utilities)
│ │ ├── tasksService.ts # Task API client
│ │ ├── projectsService.ts # Project API client
│ │ ├── notesService.ts
│ │ ├── tagsService.ts
│ │ ├── areasService.ts
│ │ ├── profileService.ts # User profile API
│ │ ├── apiKeysService.ts # API token management
│ │ ├── searchService.ts # Search API client
│ │ ├── sharesService.ts # Project sharing API
│ │ ├── backupService.ts # Backup/restore API
│ │ ├── inboxService.ts # Inbox API
│ │ ├── habitsService.ts # Habits/recurring API
│ │ ├── taskEventService.ts # Task history API
│ │ ├── taskIntelligenceService.ts # AI-assisted task mgmt
│ │ └── attachmentsService.ts # File attachment handling
│ │
│ ├── Utilities
│ │ ├── dateUtils.ts # Date/time helpers
│ │ ├── timezoneUtils.ts # Timezone handling
│ │ ├── taskSortUtils.ts # Task sorting logic
│ │ ├── localeUtils.ts # i18n helpers
│ │ ├── keyboardShortcutsService.ts # Shortcut definitions
│ │ ├── bannersService.ts # Banner management
│ │ ├── urlService.ts # URL parsing
│ │ ├── slugUtils.ts # URL slug handling
│ │ ├── userUtils.ts # User utilities
│ │ ├── fetcher.ts # SWR fetcher configuration
│ │ └── featureFlags.ts # Feature flag client
│ │
│ └── config/
│ └── paths.ts # API and path configuration
│
├── entities/ # TypeScript interfaces/types
│ ├── Task.ts # Task type definition
│ ├── Project.ts # Project type definition
│ ├── Note.ts # Note type definition
│ ├── User.ts # User type definition
│ ├── Tag.ts # Tag type definition
│ ├── Area.ts # Area type definition
│ ├── TaskEvent.ts # Task event type
│ ├── Attachment.ts # Attachment type
│ ├── InboxItem.ts # Inbox item type
│ └── Metrics.ts # Metrics type
│
├── i18n.ts # i18next configuration
│ # - Language detection
│ # - Resource loading
│ # - 24 language support
│
├── styles/ # Global styles
│ ├── globals.css
│ ├── markdown.css
│ └── ...
│
└── __tests__/ # Frontend tests
├── setup.ts # Test configuration
└── (component tests)
E2E Tests Structure
/Users/chris/c0deLab/ProjectLand/tududi/e2e/
├── tests/ # Playwright test specs
│ ├── login.spec.ts
│ ├── tasks.spec.ts
│ ├── projects.spec.ts
│ ├── subtasks.spec.ts
│ ├── recurring-tasks.spec.ts
│ └── ...
└── bin/
└── run-e2e.sh # Test runner script
Critical Paths Reference
Quick lookup table for common development tasks:
| Task | Primary Location | Related Files |
|---|---|---|
| Add backend feature | /backend/modules/[feature]/ |
routes.js, repository.js, operations/ |
| Create new model | /backend/models/[model].js |
Also update /backend/models/index.js for associations |
| Database migration | /backend/migrations/TIMESTAMP-name.js |
Create with npm run migration:create |
| Add React component | /frontend/components/[Feature]/ComponentName.tsx |
- |
| Define API routes | /backend/modules/[module]/routes.js |
- |
| Business logic | /backend/modules/[module]/operations/ |
Or service files in module |
| Global frontend state | /frontend/store/useStore.ts |
Zustand store |
| API client | /frontend/utils/[resource]Service.ts |
- |
| TypeScript types | /frontend/entities/[Type].ts |
Interface definitions |
| Backend unit tests | /backend/tests/unit/[category]/ |
models/, middleware/, services/, utils/ |
| Backend integration tests | /backend/tests/integration/[module]/ |
- |
| E2E tests | /e2e/tests/[feature].spec.ts |
Playwright specs |
| Middleware | /backend/middleware/[name].js |
auth.js, authorize.js, etc. |
| Shared utilities | /backend/utils/ or /frontend/utils/ |
Depends on context |
| Error classes | /backend/shared/errors/ |
Custom error types |
| Swagger docs | /backend/config/swagger.js |
API schema definitions |