Skip to main content

Areas

This document explains how areas work in tududi from a user behavior perspective. For technical implementation details, see the backend code in /backend/modules/areas/ and frontend components in /frontend/components/Area/.

Overview​

Areas are the highest level of organization in tududi, representing major life domains or responsibility categories. They provide a way to group projects into meaningful top-level segments.

Key characteristics:

  • Represent broad life domains (Work, Personal, Health, Finance, etc.)
  • Sit at the top of the organizational hierarchy
  • Provide high-level grouping for projects
  • Simple structure with just name and description
  • User-specific (each user has their own areas)
  • Optional organizational layer (projects can exist without areas)

Hierarchy Position:

Areas (highest level - life domains)
  └── Projects (mid level - specific goals)
        └── Tasks (actionable items)
              └── Subtasks

URL: /areas

Core Principles​

  1. Areas are top-level organizational containers

    • They represent the broadest categories of your life and work
    • Examples: Work, Personal, Health, Finance, Learning, Home

  2. Areas are optional

    • Projects can exist without belonging to an area
    • Areas provide structure but aren't required

  3. Areas don't cascade delete

    • Deleting an area orphans its projects, doesn't delete them
    • This prevents accidental data loss
    • Orphaned projects remain accessible

  4. Areas are simple by design

    • Just a name and optional description
    • No status, priority, or due dates
    • Focus is on categorization, not task management

  5. One project, one area

    • A project can belong to at most one area
    • But an area can contain many projects

Hierarchy​

Areas (highest level - life domains)
  └── Projects (mid level - specific goals/initiatives)
        ├── Tasks (actionable items)
        └── Notes (reference material)

Example structure:

Area: "Work"
  ├── Project: "Q1 Marketing Campaign"
  │     ├── Task: "Design landing page"
  │     └── Task: "Write email copy"
  ├── Project: "Website Redesign"
  │     └── Task: "Research design trends"
  └── Project: "Team Onboarding"

Area: "Personal"
  ├── Project: "Home Renovation"
  │     ├── Task: "Get contractor quotes"
  │     └── Task: "Choose paint colors"
  └── Project: "Learn Spanish"
        └── Task: "Complete Duolingo lesson"

Area: "Health"
  └── Project: "Exercise Routine"
        ├── Task: "Go for morning run"
        └── Task: "Meal prep for the week"

Area Properties​

Basic Information​

  1. Name (required)

    • The area title
    • Examples: "Work", "Personal", "Health", "Finance", "Learning"
    • Displayed in uppercase on area cards
    • Sorted alphabetically

  2. Description (optional)

    • Longer explanation of what this area encompasses
    • Helps clarify the scope and purpose
    • Displayed on area card in smaller text
    • Example: "Work related projects and professional development"

  3. UID (auto-generated)

    • Unique identifier for the area
    • Used in URLs and API calls
    • Cannot be changed

  4. User ID (system-managed)

    • Links area to the user who created it
    • Areas are private to each user
    • Cannot be shared between users

Area Lifecycle​

Creating an Area​

Ways to create:

  1. Navigate to /areas
  2. Click "New Area" button (if implemented)
  3. Use the area modal to enter details

Required fields:

  • Name (must not be empty or just whitespace)

Default values:

  • Description: Empty string

Auto-generated:

  • UID (unique identifier)
  • User ID (current user)
  • Timestamps (created_at, updated_at)

Example:

Name: "Work"
Description: "Professional projects, career development, and work-related tasks"

Editing an Area​

What you can edit:

  • Name (required, cannot be empty)
  • Description (optional)

What you cannot edit:

  • UID
  • User ID
  • Created timestamp

How to edit:

  1. Navigate to /areas
  2. Hover over area card
  3. Click three-dot menu (appears on hover)
  4. Click "Edit"
  5. Modify fields in modal
  6. Click "Save" or "Update Area"

Validation:

  • Name cannot be empty
  • Name cannot be only whitespace
  • Whitespace is trimmed from name

Deleting an Area​

What happens:

  1. Area record is deleted from database
  2. Projects belonging to area are orphaned (area_id set to null)
  3. Projects are NOT deleted
  4. Tasks and notes within projects are unaffected

What is NOT deleted:

  • Projects (they become orphaned, with no area)
  • Tasks within projects
  • Notes within projects
  • Any data except the area itself

How to delete:

  1. Navigate to /areas
  2. Hover over area card
  3. Click three-dot menu
  4. Click "Delete"
  5. Confirm deletion in dialog

Who can delete:

  • Area owner only
  • Admin users (if admin functionality exists)

No undo:

  • Deletion is permanent for the area
  • But projects can be manually reassigned to a new area

Finding orphaned projects after deletion:

  1. Go to Projects page
  2. Filter by "No Area"
  3. Re-assign to a new area if needed

Using Areas​

Viewing Areas​

Areas List Page:

  • URL: /areas
  • Shows all areas for current user
  • Displayed as a responsive grid
  • Grid adapts to screen size:
    • Mobile: 1 column
    • Tablet: 2 columns
    • Desktop: 3 columns
    • Large desktop: 4 columns

Area Cards: Each card displays:

  • Area name (uppercase, centered, large font)
  • Description (if provided, smaller text, centered)
  • Three-dot menu (appears on hover)
    • Edit option
    • Delete option

Card Layout:

  • Fixed height (120px)
  • Centered content
  • Hover effect (slight opacity change)
  • Click card to view projects in that area

Linking to Projects​

From area card:

  • Clicking an area card navigates to: /projects?area={uid}-{slug}
  • This filters the Projects page to show only projects in that area
  • Example: /projects?area=abc123-work

Slug generation:

  • Area name converted to lowercase
  • Non-alphanumeric characters replaced with hyphens
  • Leading/trailing hyphens removed
  • Example: "My Work Area" → "my-work-area"

From area detail page:

  • Displays link: "View projects in {area name}"
  • Clicking navigates to filtered projects view

Grouping Projects by Area​

On Projects page:

  • Add query parameter: ?grouped=true
  • Projects grouped under their area names
  • Special "No Area" group for orphaned projects

Example grouped view:

Work
  ├── Q1 Marketing Campaign (75% complete)
  ├── Website Redesign (30% complete)
  └── Client Onboarding (done)

Personal
  ├── Home Renovation (in progress)
  └── Learn Spanish (planned)

No Area
  └── Random Ideas (not started)

Benefits:

  • High-level overview of work distribution
  • See balance across life domains
  • Identify areas with too many/few projects

Display Rules​

Area Cards (Grid View)​

Information shown:

  • Area name (bold, uppercase, 18px)
  • Description (if exists, 12px, gray text)
  • Three-dot menu (visible on hover)

Visual design:

  • Light background: bg-gray-50 (light mode)
  • Dark background: bg-gray-900 (dark mode)
  • Rounded corners with shadow
  • Fixed height: 120px
  • Centered text alignment
  • Hover: Slight opacity reduction (90%)

Interaction:

  • Click anywhere on card → Navigate to projects filtered by area
  • Click three-dot menu → Show edit/delete options
  • Hover card → Show three-dot menu

Sorting:

  • Areas always sorted alphabetically by name (A-Z)
  • Case-insensitive sorting
  • Consistent across all views

Empty State​

When no areas exist:

  • Shows message: "No areas found" (translated)
  • Prompts user to create their first area

Area-Project Relationship​

Assigning Projects to Areas​

Ways to assign:

  1. During project creation:

    • Select area from dropdown in project modal
    • Area dropdown shows all user's areas alphabetically

  2. When editing existing project:

    • Open project detail or edit modal
    • Change area in dropdown
    • Can set to "No Area" to orphan project

  3. Bulk operations (if implemented):

    • Select multiple projects
    • Assign to area in bulk

Project can have:

  • One area (normal case)
  • No area (orphaned - still valid)
  • Cannot have multiple areas

Area Display on Projects​

On project cards:

  • Area name shown as a label/tag
  • Usually displayed below project name
  • Clickable link to filter by area

On project detail page:

  • Area name displayed in metadata section
  • Linked to area's projects list
  • Can be changed inline (if editable)

On project forms:

  • Dropdown selector for area
  • Includes "No Area" option
  • Sorted alphabetically

Orphaned Projects​

What are orphaned projects:

  • Projects with no area assigned (area_id = null)
  • Created without an area, or area was deleted
  • Perfectly valid state

How to find:

  1. Navigate to Projects page
  2. Filter by "No Area"
  3. Or use grouped view - they appear in "No Area" section

How to fix (if desired):

  1. Open orphaned project
  2. Edit project details
  3. Select an area from dropdown
  4. Save changes

Not a problem:

  • Areas are optional organizational tools
  • Projects work perfectly fine without areas
  • Some users prefer not to use areas at all

Common Workflows​

Workflow 1: Set Up Life Domains​

Scenario: Initial organization of your life

  1. Navigate to /areas
  2. Create areas for major life domains:
    • Work
    • Personal
    • Health
    • Finance
    • Learning
    • Home
  3. Add descriptions to clarify scope:
    • Work: "Professional projects and career development"
    • Personal: "Personal goals and hobbies"
    • Health: "Fitness, nutrition, and wellness"
  4. Assign existing projects to appropriate areas
  5. Review grouped projects view for balance

Workflow 2: Organize Projects into Areas​

Scenario: You have many unorganized projects

  1. Go to Projects page
  2. Filter by "No Area" to see orphaned projects
  3. For each project:
    • Open project detail
    • Consider its nature (work, personal, etc.)
    • Assign to appropriate area
  4. Use grouped view to verify organization
  5. Adjust as needed

Workflow 3: Focus on Specific Life Domain​

Scenario: You want to focus on work projects only

  1. Navigate to /areas
  2. Click on "Work" area card
  3. See only work-related projects
  4. Review active projects in work domain
  5. Identify stalled projects
  6. Plan next actions

Workflow 4: Review Life Balance​

Scenario: Check if you're balanced across domains

  1. Navigate to /projects?grouped=true
  2. See projects grouped by area
  3. Count projects in each area
  4. Identify areas with:
    • Too many projects (overcommitted)
    • Too few projects (neglected domain)
    • All completed projects (ready for new initiatives)
  5. Make adjustments to achieve balance

Workflow 5: Reorganize Life Structure​

Scenario: Your life structure has changed

  1. Navigate to /areas
  2. Edit area names/descriptions to reflect new reality
  3. Consider creating new areas:
    • New job → New work area or split areas
    • New hobby → Personal or new Learning area
  4. Delete obsolete areas (projects become orphaned)
  5. Re-assign orphaned projects to new structure
  6. Review and refine

Integration with Other Features​

Areas and Projects Page​

Filtering by area:

  • URL: /projects?area={uid}-{slug}
  • Shows only projects in that area
  • Breadcrumb or header shows current area filter
  • Can clear filter to see all projects

Grouping by area:

  • URL: /projects?grouped=true
  • Projects organized under area headings
  • Collapsible sections (if implemented)
  • Shows "No Area" group for orphaned projects

Areas and Project Detail Page​

Area shown on project:

  • Displayed in metadata section
  • Linked to area's projects list
  • Can edit to change or remove area (if permissions allow)

Areas and Navigation​

Sidebar (if areas shown):

  • May show top areas for quick access
  • Click to navigate to area's projects
  • Usually shows 3-5 most used areas

Quick filters:

  • Projects page may have area pills/tags
  • Click to toggle area filter
  • Multiple areas can be selected (OR logic)

Best Practices​

Naming Areas​

Good area names:

  • Short and clear: "Work", "Personal", "Health"
  • Broad categories, not specific projects
  • Parallel structure: All nouns or all adjectives
  • Examples: "Work", "Home", "Health", "Finance"

Avoid:

  • Overly specific: "Q1 Marketing" (that's a project)
  • Too many areas (diminishes organizational value)
  • Overlapping categories: "Work" and "Career" (redundant)
  • Vague names: "Stuff", "Things", "Other"

Structuring Your Areas​

Recommended approach:

  • Start with 4-7 major areas
  • Based on life domains, not task types
  • Examples:
    • Professional: Work, Business
    • Personal: Personal, Family, Social
    • Self-improvement: Health, Learning
    • Maintenance: Home, Finance

Too many areas:

  • Defeats the purpose of high-level organization
  • Hard to remember and maintain
  • Projects get scattered
  • Consider: Do you really need that area?

Too few areas:

  • Everything in "Work" and "Personal"
  • Loses organizational granularity
  • Consider: Are you neglecting important life domains?

Using Descriptions​

Good descriptions:

  • Clarify the scope of the area
  • Help with project assignment decisions
  • Examples:
    • "Work": "Professional projects, career development, and work relationships"
    • "Health": "Physical fitness, nutrition, mental wellness, and medical care"
    • "Learning": "Online courses, reading, language learning, and skill development"

When to skip descriptions:

  • Area name is self-explanatory ("Personal", "Work")
  • You're the only user and know what it means

Maintaining Your Areas​

Regular review:

  • Every 3-6 months, review your areas
  • Are they still relevant to your life?
  • Do you need to add/remove/rename areas?
  • Are projects correctly categorized?

When life changes:

  • New job → Adjust work areas
  • New responsibility → Add new area
  • Completed major goal → Remove or repurpose area

Troubleshooting​

"My projects disappeared when I deleted the area"​

What happened:

  • Projects are not deleted, they're orphaned
  • They still exist in your database

How to find:

  1. Go to Projects page
  2. Filter by "No Area"
  3. You'll see all orphaned projects
  4. Re-assign to a new area if needed

"I can't see my area in the projects dropdown"​

Possible causes:

  1. Area belongs to different user (not shared)
  2. Area was deleted
  3. Frontend cache issue

How to fix:

  1. Refresh the page
  2. Check /areas page to confirm area exists
  3. If missing, recreate the area

"Area cards not showing in grid"​

Possible causes:

  1. No areas created yet
  2. Loading state
  3. API error

How to check:

  1. Wait for loading to complete
  2. Check browser console for errors
  3. Verify /api/areas endpoint returns data
  4. Create first area if none exist

"Projects grouped view not working"​

Checklist:

  1. Is ?grouped=true in URL?
  2. Do projects have area_id set?
  3. Are areas loaded in global state?
  4. Check browser console for errors

"Can't delete an area"​

Possible reasons:

  1. You're not the owner (areas can't be shared)
  2. Network error
  3. Permission issue

Alternative:

  • If you can't delete, just don't use it
  • Remove all projects from the area
  • It won't show up in grouped views

Use Cases​

1. Life-Work Balance Monitoring​

Areas help you see if you're:

  • Overcommitting in work area
  • Neglecting personal projects
  • Ignoring health/fitness
  • Balancing across all domains

Action: Review grouped projects view monthly

2. Context Switching​

When switching contexts (work → personal):

  • Click area card to see relevant projects
  • Focus on that domain exclusively
  • Avoid distraction from other areas

Action: Use area filters during focused work sessions

3. Goal Setting Across Life Domains​

Ensure you have:

  • Active projects in each important area
  • Balance between maintenance and growth
  • Projects in neglected domains

Action: Set quarterly goals per area

4. Delegation and Collaboration​

Though areas themselves aren't shared:

  • Projects within areas can be shared
  • Use areas to organize shared vs. personal work
  • Example: "Work" area has shared team projects

Action: Keep team projects in shared areas

5. Year-End Review​

At year end, review each area:

  • How many projects completed?
  • Which areas were neglected?
  • Where did you make most progress?
  • What needs attention next year?

Action: Annual area-by-area retrospective

Technical Notes​

Data Model​

Database table: areas

Columns:

  • id (integer, primary key, auto-increment)
  • uid (string, unique, auto-generated)
  • name (string, required)
  • description (string, optional)
  • user_id (integer, foreign key to users table)
  • created_at (timestamp)
  • updated_at (timestamp)

Indexes:

  • Primary key on id
  • Unique index on uid
  • Index on user_id (for fast user-based queries)

API Endpoints​

GET /api/areas

  • List all areas for current user
  • Sorted alphabetically by name
  • Returns: Array of area objects

GET /api/areas/:uid

  • Get single area by UID
  • Returns: Area object

POST /api/areas

  • Create new area
  • Body: { name, description }
  • Returns: Created area object (201)

PATCH /api/areas/:uid

  • Update existing area
  • Body: { name?, description? }
  • Returns: Updated area object

DELETE /api/areas/:uid

  • Delete area (orphans projects)
  • Returns: 204 No Content

Authentication:

  • All endpoints require authentication
  • 401 if not authenticated

Validation Rules​

Name validation:

  • Required (cannot be null or undefined)
  • Cannot be empty string
  • Cannot be only whitespace
  • Whitespace trimmed before saving

Description validation:

  • Optional
  • Can be empty string or null
  • Stored as empty string if not provided

UID validation:

  • Must be valid string format
  • Checked when getting/updating/deleting

Technical Implementation Files:

  • Area model: /backend/models/area.js
  • Areas service: /backend/modules/areas/service.js
  • Areas controller: /backend/modules/areas/controller.js
  • Areas repository: /backend/modules/areas/repository.js
  • Areas routes: /backend/modules/areas/routes.js
  • Areas validation: /backend/modules/areas/validation.js
  • Frontend components: /frontend/components/Area/
  • Areas list page: /frontend/components/Areas.tsx
  • Area detail page: /frontend/components/Area/AreaDetails.tsx
  • Area modal: /frontend/components/Area/AreaModal.tsx
  • Areas API client: /frontend/utils/areasService.ts
  • Integration tests: /backend/tests/integration/areas.test.js

Document Version: 1.0.0 Last Updated: 2026-03-14 Audience: Developers, AI assistants, and end users