break-it-down/ARCHIVE_FEATURE_README.md

Project Archive Feature

Overview

The Break It Down (BIT) application now supports archiving projects! This helps you organize your workspace by hiding completed or inactive projects from the main view while keeping them accessible.

Features Added

1. Archive Status

• Projects can be marked as archived or active
• Archived projects are kept in the database but hidden from the default view
• All tasks and data are preserved when archiving

2. Tab Navigation

The main Projects page now has three tabs:

• Active (default) - Shows only non-archived projects
• Archived - Shows only archived projects
• All - Shows all projects regardless of archive status

3. Quick Actions

Each project card now has two action buttons:

• Archive/Unarchive (📦/↩️) - Toggle archive status
• Delete (🗑️) - Permanently delete the project

4. Visual Indicators

• Archived projects appear with reduced opacity and gray border
• "(archived)" label appears next to archived project names
• Context-aware empty state messages

Database Changes

A new column has been added to the projects table:

• is_archived (BOOLEAN) - Defaults to False for new projects

Installation & Migration

For New Installations

No action needed! The database will be created with the correct schema automatically.

For Existing Databases

If you have an existing Break It Down database, run the migration script:

cd backend
python3 migrate_add_is_archived.py

This will add the is_archived column to your existing projects table and set all existing projects to is_archived=False.

Restart the Backend

After migration, restart the backend server to load the updated models:

# Stop the current backend process
pkill -f "uvicorn.*backend.main:app"

# Start the backend again
cd /path/to/break-it-down
uvicorn backend.main:app --host 0.0.0.0 --port 8001

Or if using Docker:

docker-compose restart backend

API Changes

Updated Endpoint: GET /api/projects

New optional query parameter:

• archived (boolean, optional) - Filter projects by archive status
  • archived=false - Returns only active projects
  • archived=true - Returns only archived projects
  • No parameter - Returns all projects

Examples:

# Get active projects
GET /api/projects?archived=false

# Get archived projects
GET /api/projects?archived=true

# Get all projects
GET /api/projects

Updated Endpoint: PUT /api/projects/{id}

New field in request body:

{
  "name": "Project Name",          // optional
  "description": "Description",    // optional
  "statuses": [...],              // optional
  "is_archived": true             // optional - new!
}

New API Helper Functions

The frontend API client now includes:

• archiveProject(id) - Archive a project
• unarchiveProject(id) - Unarchive a project

File Changes Summary

Backend

• backend/app/models.py - Added is_archived Boolean column to Project model
• backend/app/schemas.py - Updated ProjectUpdate and Project schemas
• backend/app/main.py - Added archived query parameter to list_projects endpoint
• backend/app/crud.py - Updated get_projects to support archive filtering
• backend/migrate_add_is_archived.py - Migration script (new file)

Frontend

• frontend/src/pages/ProjectList.jsx - Added tabs, archive buttons, and filtering logic
• frontend/src/utils/api.js - Added archive/unarchive functions and updated getProjects

Usage Examples

Archive a Project

1. Go to the Projects page
2. Click the archive icon (📦) on any project card
3. The project disappears from the Active view
4. Switch to the "Archived" tab to see it

Unarchive a Project

1. Switch to the "Archived" tab
2. Click the unarchive icon (↩️) on the project card
3. The project returns to the Active view

View All Projects

Click the "All" tab to see both active and archived projects together.

Status vs Archive

Important distinction:

• Task Status (backlog, in_progress, on_hold, done) - Applied to individual tasks within a project
• Project Archive - Applied to entire projects to organize your workspace

The existing task status "on_hold" is still useful for pausing work on specific tasks, while archiving is for entire projects you want to hide from your main view.

Backward Compatibility

All changes are backward compatible:

• Existing projects will default to is_archived=false (active)
• Old API calls without the archived parameter still work (returns all projects)
• The frontend gracefully handles projects with or without the archive field

Future Enhancements

Potential additions:

• Archive date tracking
• Bulk archive operations
• Archive projects from the ProjectSettings modal
• Auto-archive projects after X days of inactivity
• Project status badges (active, archived, on-hold, completed)