# Tududi - Developer Guide

This documentation is designed for AI assistants and developers working with the tududi codebase. For user-facing documentation, see [README.md](README.md). For contribution guidelines, see [CONTRIBUTING.md](.github/CONTRIBUTING.md).

---

## Quick Start

Tududi is a self-hosted task management system with hierarchical organization (Areas > Projects > Tasks), smart recurring tasks, and multi-channel integration.

**Tech Stack:** React 18 + TypeScript, Express + Sequelize, SQLite

**Get Started:**
```bash
git clone https://github.com/chrisvel/tududi.git
cd tududi
npm install
npm run db:init
npm start  # Frontend on :8080, Backend on :3002
```

---

## Documentation Index

### Core Documentation

1. **[Architecture Overview](docs/architecture.md)**
   - Tech stack details
   - Request flow diagram
   - Data model hierarchy
   - Authentication methods

2. **[Directory Structure](docs/directory-structure.md)**
   - Complete file tree with absolute paths
   - Critical paths reference
   - Backend and frontend organization

3. **[Backend Patterns](docs/backend-patterns.md)**
   - Module architecture pattern
   - How to add new modules
   - Module communication
   - Repository and service patterns

4. **[Database & Migrations](docs/database.md)**
   - Key models and relationships
   - Migration workflow
   - Migration best practices
   - Common migration operations

5. **[Backups & Restoration](docs/backups.md)**
   - Automatic SQLite file backups before migrations
   - Backup retention policies (4 per day, 1 per day for 7 days)
   - Restoration procedures for development, Docker, and production
   - Emergency restore after failed migrations
   - Best practices for data safety

6. **[Development Workflow](docs/development-workflow.md)**
   - Initial setup
   - Daily development (two-server process)
   - Environment variables
   - Adding new features (complete walkthrough)
   - Database management commands

7. **[Code Conventions](docs/code-conventions.md)**
   - Language usage (TypeScript/JavaScript)
   - Backend patterns (async/await, repository)
   - Frontend patterns (components, state)
   - Naming conventions
   - API route conventions

8. **[Testing](docs/testing.md)**
   - Test organization
   - Running tests
   - Testing requirements
   - Test patterns (Arrange-Act-Assert)

9. **[Common Tasks](docs/common-tasks.md)**
   - Add field to model
   - Create new backend module
   - Add React component
   - Update database schema
   - Fix a bug (TDD workflow)
   - Add translations

10. **[Tasks Behavior](docs/00-tasks-behavior.md)**
    - Task creation and basic fields
    - Status lifecycle and priority levels
    - Due dates and Defer Until
    - Subtasks and hierarchy
    - File attachments
    - Project assignment and tags
    - Task completion and history
    - Habit mode and tracking
    - Task deletion and permissions

11. **[Recurring Tasks Behavior](docs/01-recurring-tasks-behavior.md)**
    - How recurring tasks work (non-technical rules)
    - Completion behavior and patterns
    - Virtual instances and display rules
    - Parent-child relationships
    - Editing and deletion behavior

12. **[Today Page Sections](docs/02-today-page-sections.md)**
    - How Overdue, Planned, Suggested, and Completed sections work
    - Task filtering and display rules
    - Section priority and deduplication logic
    - User settings and customization
    - Defer Until and timezone handling

13. **[Upcoming View](docs/03-upcoming-view.md)**
    - How the 7-day Upcoming view works
    - Day-based grouping and organization
    - Recurring task virtual occurrences
    - Defer Until and status filtering
    - Differences from Today view

14. **[Inbox Page](docs/04-inbox-page.md)**
    - Quick capture system for unorganized thoughts
    - Smart parsing of hashtags, projects, and URLs
    - Intelligent suggestions (Task vs Note vs Project)
    - Converting inbox items to structured content
    - Telegram integration and auto-refresh
    - Keyboard shortcuts and workflows

15. **[Notes System](docs/05-notes-system.md)**
    - Flexible information and reference storage
    - Markdown support and rich text rendering
    - Auto-save functionality (1-second debounce)
    - Project linking and tag-based organization
    - Focus mode for distraction-free writing
    - Color customization for visual organization
    - Integration with inbox and project workflows

16. **[Projects](docs/06-projects.md)**
    - Project hierarchy and organization (Areas > Projects > Tasks)
    - Status lifecycle and stalled detection
    - Completion tracking and progress metrics
    - Project sharing and collaboration permissions
    - Due dates, notifications, and priorities
    - Deletion behavior (orphaning vs cascading)
    - Filtering, grouping, and sidebar pinning

17. **[Areas](docs/07-areas.md)**
    - Top-level organizational categories for life domains
    - Simple structure with name and description
    - Optional containers for grouping projects
    - Cascade behavior when deleting (orphans projects)
    - Grid view with alphabetical sorting
    - Integration with Projects page filtering and grouping

18. **[Views System](docs/08-views-system.md)**
    - Smart saved searches for tasks, notes, and projects
    - Creating views from Universal Search
    - Pinning and reordering views in sidebar
    - Filtering, sorting, and grouping within views
    - View management (rename, delete, pin/unpin)
    - URL parameters and deep linking
    - Pagination and performance

19. **[User Management](docs/08-user-management.md)**
    - Registration flow and email verification
    - Authentication (session-based and API tokens)
    - User roles and admin system
    - Resource permissions and sharing
    - Profile management and preferences
    - Password and avatar management
    - API token management
    - Admin user CRUD operations

20. **[Tags System](docs/09-tags-system.md)**
    - Cross-entity labeling and categorization (tasks, notes, projects)
    - Auto-creation and validation rules
    - Tag management (create, edit, delete, rename)
    - Tag detail pages with filtering and search
    - Alphabetical grouping and organization
    - Hashtag parsing from inbox items
    - Tag input component with autocomplete

21. **[Claude Memory & Preferences](docs/MEMORY.md)**
    - PR and commit message preferences
    - Testing preferences
    - Common patterns to remember
    - Known issues and solutions

---

## Project Overview

### What This Project Does

Tududi is a self-hosted task management system designed around hierarchical organization and smart automation. It prioritizes user flow over rigid structures - a productivity tool that doesn't "fight back."

**Core Philosophy:**
- [Designing a Life Management System That Doesn't Fight Back](https://medium.com/@chrisveleris/designing-a-life-management-system-that-doesnt-fight-back-2fd58773e857)
- [From Task to Table: How I Finally Got to the Korean Burger](https://medium.com/@chrisveleris/from-task-to-table-how-i-finally-got-to-the-korean-burger-01245a14d491)

**Key Capabilities:**
- **Hierarchical Organization:** Areas > Projects > Tasks > Subtasks
- **Smart Recurring Tasks:** Multiple patterns with parent-child tracking
- **Multi-Language Support:** 24 languages via i18next
- **Collaboration:** Project sharing with granular permissions
- **REST API:** Swagger docs + personal API tokens
- **Telegram Integration:** Create tasks via messages, daily digests
- **Tag System:** Flexible tagging across tasks, notes, projects

**Target Users:** Self-hosting individuals and teams managing personal or collaborative productivity

---

## Technology Stack

**Frontend:**
- React 18 + TypeScript 5.6
- Webpack 5 (build) + webpack-dev-server (development)
- Tailwind CSS 3.4 + Heroicons
- Zustand (global state) + SWR (server state)
- React Router 6, i18next (24 languages)

**Backend:**
- Express 4.21 + Sequelize 6.37 (ORM)
- SQLite 5.1 (WAL mode, optimized)
- bcrypt + express-session (auth)
- Swagger (API docs), Multer (uploads)
- node-cron (scheduling), Nodemailer (email)

**Testing:**
- Jest (backend + frontend)
- Playwright (E2E)
- Supertest (API integration tests)

---

## Critical Paths Quick Reference

| Task | Location |
|------|----------|
| Add backend feature | `/backend/modules/[feature]/` |
| Create model | `/backend/models/[model].js` |
| Database migration | `/backend/migrations/` |
| React component | `/frontend/components/[Feature]/` |
| API routes | `/backend/modules/[module]/routes.js` |
| Global state | `/frontend/store/useStore.ts` |
| API client | `/frontend/utils/[resource]Service.ts` |

---

## Related Documentation

| Document | Audience | Purpose |
|----------|----------|---------|
| [README.md](README.md) | Users | Features, Docker setup, quick start |
| [CONTRIBUTING.md](.github/CONTRIBUTING.md) | Contributors | PR workflow, code of conduct |
| [docs.tududi.com](https://docs.tududi.com) | End users | Full user documentation |
| [Swagger API docs](http://localhost:3002/api-docs) | API consumers | API endpoints (after auth) |
| **CLAUDE.md** | Developers, AI | Codebase architecture, patterns |

---

## External Resources

- **Roadmap:** [GitHub Project](https://github.com/users/chrisvel/projects/2)
- **Community:**
  - [Discord](https://discord.gg/fkbeJ9CmcH)
  - [Reddit](https://www.reddit.com/r/tududi/)
  - [Issues](https://github.com/chrisvel/tududi/issues)
  - [Discussions](https://github.com/chrisvel/tududi/discussions)

---

**Document Version:** 1.0.0
**Last Updated:** 2026-03-14
**Maintainer:** Update when architecture changes or patterns evolve