161 lines
4.8 KiB
Markdown
161 lines
4.8 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
# 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:
|
|
```json
|
|
{
|
|
"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)
|