# Life OS - Development Status & Continuation Guide (Convo 4)

**Last Updated:** 2026-02-28
**Current State:** Phase 1 - Tier 3 in progress (2 of 6 features built, time tracking UX complete)
**GitHub:** mdombaugh/lifeos-dev (main branch)

---

## 1. What Was Built in This Conversation

### Timer Buttons on Task UI (DEPLOYED)
- Play/stop button on each non-completed task row in tasks.html (between checkbox and priority dot)
- Play/stop button in task_detail.html header action bar (before Edit/Complete buttons)
- Running task row gets green left border highlight via `.timer-active` CSS class
- `get_running_task_id()` helper in routers/tasks.py queries `time_entries WHERE end_at IS NULL`
- Both list_tasks and task_detail routes pass `running_task_id` to template context
- Buttons POST to existing `/time/start` and `/time/stop` endpoints, redirect back via referer
- Only shown on non-completed, non-cancelled tasks
- ~60 lines of CSS appended to style.css (timer-btn, timer-btn-play, timer-btn-stop, timer-active, timer-detail-btn)
- Deployed via heredoc shell script (deploy-timer-buttons.sh)

This completes the Time Tracking feature. The full time tracking system is now:
- Start/stop timer per task from task list rows, task detail page, or time log page
- Topbar timer pill with green pulsing dot, task name link, live elapsed counter, stop button
- Auto-stop of running timer when starting a new one
- Manual time entry support
- Time log at /time with daily summaries, date-grouped entries, day filter
- Soft delete via direct SQL (time_entries lacks updated_at column)

### What Was NOT Built (deferred to Convo 5)
- **Processes / process_runs** - Most complex Tier 3 feature. 4 tables. Deferred due to usage limits.
- **Calendar view** - Unified read-only view
- **Time budgets** - Simple CRUD
- **Eisenhower matrix** - Derived view

---

## 2. Complete Application Inventory

### 2.1 Infrastructure (unchanged)

| Component | Status | Details |
|-----------|--------|---------|
| Server | LIVE | defiant-01, Hetzner, 46.225.166.142, Ubuntu 24.04 |
| Docker network | LIVE | `lifeos_network` (172.21.0.0/16) |
| PostgreSQL | LIVE | Container `lifeos-db`, postgres:16-alpine, volume `lifeos_db_data` |
| Databases | LIVE | `lifeos_prod` (R0 data, untouched), `lifeos_dev` (R1 schema + migrated data) |
| Application | LIVE | Container `lifeos-dev`, port 8003, image `lifeos-app` |
| Nginx | LIVE | lifeos-dev.invixiom.com -> localhost:8003 |
| SSL | LIVE | Let's Encrypt cert at `/etc/letsencrypt/live/kasm.invixiom.com-0001/` |
| GitHub | PUSHED | Convo 3 changes pushed. Convo 4 changes need push (see section 4.2). |

### 2.2 Core Modules

- `core/database.py` - Async engine, session factory, get_db dependency
- `core/base_repository.py` - Generic CRUD: list, get, create, update, soft_delete, restore, permanent_delete, bulk_soft_delete, reorder, count, list_deleted. Has `nullable_fields` set for update() null handling.
- `core/sidebar.py` - Domain > area > project nav tree, capture/focus badge counts
- `main.py` - FastAPI app, dashboard, health check, 18 router includes

### 2.3 Routers (18 total)

| Router | Prefix | Templates | Status |
|--------|--------|-----------|--------|
| domains | /domains | domains, domain_form | Convo 1 |
| areas | /areas | areas, area_form | Convo 1 |
| projects | /projects | projects, project_form, project_detail | Convo 1 |
| tasks | /tasks | tasks, task_form, task_detail | Convo 1, **updated Convo 4** |
| notes | /notes | notes, note_form, note_detail | Convo 1 |
| links | /links | links, link_form | Convo 1 |
| focus | /focus | focus | Convo 1 |
| capture | /capture | capture | Convo 1 |
| contacts | /contacts | contacts, contact_form, contact_detail | Convo 1 |
| search | /search | search | Convo 2 |
| admin | /admin/trash | trash | Convo 2 |
| lists | /lists | lists, list_form, list_detail | Convo 2 |
| files | /files | files, file_upload, file_preview | Convo 2 |
| meetings | /meetings | meetings, meeting_form, meeting_detail | Convo 2 |
| decisions | /decisions | decisions, decision_form, decision_detail | Convo 2 |
| weblinks | /weblinks | weblinks, weblink_form, weblink_folder_form | Convo 2 |
| appointments | /appointments | appointments, appointment_form, appointment_detail | Convo 3 |
| time_tracking | /time | time_entries | Convo 3 |

### 2.4 Templates (42 total, unchanged from Convo 3)

base.html, dashboard.html, search.html, trash.html,
tasks.html, task_form.html, task_detail.html,
projects.html, project_form.html, project_detail.html,
domains.html, domain_form.html,
areas.html, area_form.html,
notes.html, note_form.html, note_detail.html,
links.html, link_form.html,
focus.html, capture.html,
contacts.html, contact_form.html, contact_detail.html,
lists.html, list_form.html, list_detail.html,
files.html, file_upload.html, file_preview.html,
meetings.html, meeting_form.html, meeting_detail.html,
decisions.html, decision_form.html, decision_detail.html,
weblinks.html, weblink_form.html, weblink_folder_form.html,
appointments.html, appointment_form.html, appointment_detail.html,
time_entries.html

### 2.5 Static Assets

- `style.css` - ~1040 lines (timer button CSS appended in Convo 4)
- `app.js` - ~190 lines (timer pill polling from Convo 3, unchanged in Convo 4)

---

## 3. How the Container Runs

```bash
docker run -d \
  --name lifeos-dev \
  --network lifeos_network \
  --restart unless-stopped \
  --env-file .env \
  -p 8003:8003 \
  -v /opt/lifeos/dev/files:/opt/lifeos/files/dev \
  -v /opt/lifeos/dev:/app \
  lifeos-app \
  uvicorn main:app --host 0.0.0.0 --port 8003 --workers 1 --reload
```

**Environment (.env):**
```
DATABASE_URL=postgresql+asyncpg://postgres:UCTOQDZiUhN8U@lifeos-db:5432/lifeos_dev
FILE_STORAGE_PATH=/opt/lifeos/files/dev
ENVIRONMENT=development
```

Deploy: edit files in `/opt/lifeos/dev/`, hot reload picks them up.
Restart: `docker restart lifeos-dev`
Logs: `docker logs lifeos-dev --tail 30`

---

## 4. Known Issues

### 4.1 Immediate
1. **Not yet tested by user** - Timer buttons deployed but user testing still pending. May have bugs.
2. **Convo 4 changes not pushed to GitHub** - Run: `cd /opt/lifeos/dev && git add . && git commit -m "Timer buttons on task rows and detail" && git push origin main`

### 4.2 Technical Debt
1. **time_entries missing `updated_at`** - Table lacks this column so BaseRepository methods that set updated_at will fail. Direct SQL used for soft_delete. If adding time_entries to TRASH_ENTITIES, restore will also need direct SQL.
2. **R1 schema file mismatch** - lifeos_schema_r1.sql in project doesn't reflect actual DB. Query DB directly to verify.
3. **No CSRF protection** - Single-user system, low risk.
4. **No pagination** - All list views load all rows. Fine at current scale.
5. **Font loading** - Google Fonts @import is render-blocking.

---

## 5. What's NOT Built Yet

### Tier 3 Remaining (4 features)
1. **Processes / process_runs** - Most complex Tier 3 feature. 4 tables: processes, process_steps, process_runs, process_run_steps. Template CRUD, run instantiation (copies steps as immutable snapshot), step completion tracking, task generation modes (all_at_once vs step_by_step). START HERE in Convo 5.
2. **Calendar view** - Unified `/calendar` page showing appointments (start_at) + meetings (meeting_date) + tasks (due_date). No new tables, read-only derived view. Filter by date range, domain, type.
3. **Time budgets** - Simple CRUD: domain_id + weekly_hours + effective_from. Used for overcommitment warnings on dashboard.
4. **Eisenhower matrix** - Derived 2x2 grid from task priority + due_date. Quadrants: Important+Urgent (priority 1-2, due <=7d), Important+Not Urgent (priority 1-2, due >7d), Not Important+Urgent (priority 3-4, due <=7d), Not Important+Not Urgent (priority 3-4, due >7d or null). Clickable to filter task list.

### Tier 4 - Advanced Features
- Releases / milestones
- Dependencies (DAG, cycle detection, status cascade)
- Task templates (instantiation with subtask generation)
- Note wiki-linking ([[ syntax)
- Note folders
- Bulk actions (multi-select, bulk complete/move/delete)
- CSV export
- Drag-to-reorder (SortableJS)
- Reminders
- Weekly review process template
- Dashboard metrics (weekly/monthly completion stats)

### UX Polish
- Breadcrumb navigation (partially done, inconsistent)
- Overdue visual treatment (red left border on task rows)
- Empty states with illustrations (basic emoji states exist)
- Skeleton loading screens
- Toast notification system
- Confirmation dialogs (basic confirm() exists, no modal)
- Mobile bottom tab bar
- Mobile responsive improvements

---

## 6. File Locations on Server

```
/opt/lifeos/
  dev/                     # DEV application (mounted as /app in container)
    main.py                # 18 router includes
    core/
      __init__.py
      database.py
      base_repository.py
      sidebar.py
    routers/
      __init__.py
      domains.py, areas.py, projects.py, tasks.py
      notes.py, links.py, focus.py, capture.py, contacts.py
      search.py, admin.py, lists.py
      files.py, meetings.py, decisions.py, weblinks.py
      appointments.py
      time_tracking.py
    templates/
      base.html, dashboard.html, search.html, trash.html
      tasks.html, task_form.html, task_detail.html
      projects.html, project_form.html, project_detail.html
      domains.html, domain_form.html
      areas.html, area_form.html
      notes.html, note_form.html, note_detail.html
      links.html, link_form.html
      focus.html, capture.html
      contacts.html, contact_form.html, contact_detail.html
      lists.html, list_form.html, list_detail.html
      files.html, file_upload.html, file_preview.html
      meetings.html, meeting_form.html, meeting_detail.html
      decisions.html, decision_form.html, decision_detail.html
      weblinks.html, weblink_form.html, weblink_folder_form.html
      appointments.html, appointment_form.html, appointment_detail.html
      time_entries.html
    static/
      style.css (~1040 lines)
      app.js (~190 lines)
    Dockerfile
    requirements.txt
    .env
  backups/                 # Database backups
```

---

## 7. How to Continue Development

### Recommended build order for Convo 5:
1. **Processes / process_runs** (most complex remaining feature - do first with full usage window)
2. **Calendar view** (combines appointments + meetings + tasks)
3. **Time budgets** (simple CRUD)
4. **Eisenhower matrix** (derived view, quick win)

### Adding a new entity router (pattern):
1. Create `routers/entity_name.py` following existing router patterns
2. Add import + `app.include_router()` in `main.py`
3. Create templates: list, form, detail (all extend base.html)
4. Add nav link in `templates/base.html` sidebar section
5. Add to `SEARCH_ENTITIES` in `routers/search.py` (if searchable)
6. Add to `TRASH_ENTITIES` in `routers/admin.py` (if soft-deletable)
7. Add any new nullable fields to `nullable_fields` in `core/base_repository.py`
8. Use `BaseRepository("table_name", db)` for all CRUD
9. Always call `get_sidebar_data(db)` and pass to template context

### Deploy cycle:
```bash
# Files are created locally by Claude, packaged as a deploy script with heredocs
# Upload to server, run the script
scp deploy-script.sh root@46.225.166.142:/opt/lifeos/dev/
ssh root@46.225.166.142
cd /opt/lifeos/dev && bash deploy-script.sh

# Commit
git add . && git commit -m "description" && git push origin main
```

### Database backup:
```bash
mkdir -p /opt/lifeos/backups
docker exec lifeos-db pg_dump -U postgres -d lifeos_dev -Fc -f /tmp/lifeos_dev_backup.dump
docker cp lifeos-db:/tmp/lifeos_dev_backup.dump /opt/lifeos/backups/lifeos_dev_$(date +%Y%m%d_%H%M%S).dump
```

### Key code patterns:
- Every route: `sidebar = await get_sidebar_data(db)`
- Forms POST to /create or /{id}/edit, redirect 303
- Filters: query params, auto-submit via JS onchange
- Detail views: breadcrumb nav at top
- Toggle/complete: inline form with checkbox onchange
- Junction tables: raw SQL INSERT with ON CONFLICT DO NOTHING
- File upload: multipart form, save to FILE_STORAGE_PATH, record in files table
- Timer: POST /time/start with task_id, POST /time/stop, GET /time/running (JSON for topbar pill)
- Timer buttons: get_running_task_id() helper in tasks.py, play/stop inline forms on task rows

---

## 8. Tier 3 Architecture Reference

### Processes / Process Runs (BUILD NEXT)
**Tables:** processes, process_steps, process_runs, process_run_steps

**Flow:**
1. Create a process template (processes) with ordered steps (process_steps)
2. Instantiate a run (process_runs) - copies all process_steps to process_run_steps as immutable snapshots
3. Steps in a run can be completed, which records completed_by_id and completed_at
4. Task generation modes: `all_at_once` creates all tasks when run starts, `step_by_step` creates next task only when current step completes
5. Template changes after run creation do NOT affect active runs (snapshot pattern)

**Schema notes:**
- processes: id, name, description, process_type (workflow|checklist), category, status, tags, search_vector
- process_steps: id, process_id, title, instructions, expected_output, estimated_days, context, sort_order
- process_runs: id, process_id, title, status, process_type (copied from template), task_generation, project_id, contact_id, started_at, completed_at
- process_run_steps: id, run_id, title, instructions (immutable), status, completed_by_id, completed_at, notes, sort_order

### Calendar View
- Unified read-only page at `/calendar`
- Show appointments (start_at), meetings (meeting_date + start_at), tasks (due_date)
- Filter by date range, domain, type
- No new tables needed

### Time Budgets
- Simple CRUD: domain_id + weekly_hours + effective_from
- Dashboard warning when domain time_entries exceed budget

### Eisenhower Matrix
- Derived from task priority (1-4) + due_date
- Quadrants: Important+Urgent, Important+Not Urgent, Not Important+Urgent, Not Important+Not Urgent
- Priority 1-2 = Important, Priority 3-4 = Not Important
- Due <= 7 days or overdue = Urgent, Due > 7 days or no date = Not Urgent
- Rendered as 2x2 grid, clicking quadrant filters to task list

---

## 9. Production Deployment (Not Yet Done)

When ready to go to PROD:
1. Apply R1 schema to lifeos_prod
2. Run data migration on lifeos_prod
3. Build and start lifeos-prod container on port 8002
4. Nginx already has lifeos.invixiom.com block pointing to 8002
5. SSL cert already covers lifeos.invixiom.com
6. Set ENVIRONMENT=production in prod .env
7. Set up daily backup cron job