giteadmin/lifeos-prod
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5297da485f64167f9ad8da137ef818370373e4ab
lifeos-prod/project-docs/lifeos-architecture.docx
Michael 5297da485f Initial commit
2026-03-03 00:44:33 +00:00

3426 lines
113 KiB
Plaintext
Raw Blame History

**LIFE OS**
Architecture Design Document
Complete System Specification --- All Layers
-------------------- ----------------------------------------------------
**Document Type** Final Architecture Design
**Version** 2.0 --- February 2026
**Status** Approved for Build
**Author** M. Dombaugh
**Server** defiant-01 46.225.166.142
**Production URL** lifeos.invixiom.com
**Dev URL** lifeos-dev.invixiom.com
**Repository** github.com/mdombaugh/life-os
**Backend** Python 3.12 / FastAPI / SQLAlchemy
**Database** PostgreSQL 16
**Infrastructure** Docker / Nginx / Let\'s Encrypt
**Phases** Phase 1 (build) / Phase 2 (AI) / Phase 3 (polish)
-------------------- ----------------------------------------------------
-----------------------------------------------------------------------
**Table of Contents**
-----------------------------------------------------------------------
-------- --------------------------------------------------------- -------
**1.** Vision and Goals 3
-------- --------------------------------------------------------- -------
-------- --------------------------------------------------------- -------
**2.** Functional Requirements 4
-------- --------------------------------------------------------- -------
-------- --------------------------------------------------------- -------
**3.** Non-Functional Requirements 6
-------- --------------------------------------------------------- -------
-------- --------------------------------------------------------- -------
**4.** System Architecture Overview 7
-------- --------------------------------------------------------- -------
-------- --------------------------------------------------------- -------
**5.** Subsystems and Capabilities 9
-------- --------------------------------------------------------- -------
-------- --------------------------------------------------------- -------
**6.** Data Architecture 12
-------- --------------------------------------------------------- -------
-------- --------------------------------------------------------- -------
**7.** Application Layer Architecture 22
-------- --------------------------------------------------------- -------
-------- --------------------------------------------------------- -------
**8.** Generic Code Architecture 25
-------- --------------------------------------------------------- -------
-------- --------------------------------------------------------- -------
**9.** Frontend Architecture 27
-------- --------------------------------------------------------- -------
--------- --------------------------------------------------------- -------
**10.** Infrastructure Architecture 30
--------- --------------------------------------------------------- -------
--------- --------------------------------------------------------- -------
**11.** Search Architecture 33
--------- --------------------------------------------------------- -------
--------- --------------------------------------------------------- -------
**12.** Time Management Architecture 34
--------- --------------------------------------------------------- -------
--------- --------------------------------------------------------- -------
**13.** AI and MCP Architecture 36
--------- --------------------------------------------------------- -------
--------- --------------------------------------------------------- -------
**14.** Security Architecture 38
--------- --------------------------------------------------------- -------
--------- --------------------------------------------------------- -------
**15.** Phase Build Plan 39
--------- --------------------------------------------------------- -------
--------- --------------------------------------------------------- -------
**16.** Migration Plan 42
--------- --------------------------------------------------------- -------
--------- --------------------------------------------------------- -------
**17.** Appendix: Table Inventory 43
--------- --------------------------------------------------------- -------
-----------------------------------------------------------------------
**1. Vision and Goals**
-----------------------------------------------------------------------
**1.1 Vision Statement**
Life OS is a personal productivity platform that unifies every aspect of
professional and personal work into a single, structured system. It
eliminates context-switching between disconnected tools by providing a
single source of truth for tasks, projects, knowledge, decisions,
relationships, meetings, processes, time, and releases. The system is
designed to grow with the user\'s workload without becoming unwieldy,
through consistent hierarchical organization, powerful search, and AI
assistance.
**1.2 Problem Statement**
- Too many disconnected tools: tasks in one place, notes in another,
contacts in a CRM, meetings in a calendar, decisions nowhere.
Context is lost between tools.
- Too much to do, too little time: no visibility into total committed
work versus available capacity. Overcommitment is invisible until it
becomes a crisis.
- Knowledge dispersal: decisions, rationale, and meeting outcomes are
not captured systematically. Institutional knowledge is lost or hard
to find.
- No process memory: recurring work is redone from scratch each time
instead of being captured as a reusable, improvable process.
- Reactive instead of proactive: without a structured daily focus and
time budget system, urgent work crowds out important work.
**1.3 Strategic Goals**
---------------- ------------------------------------------------------
**G1 - Single One system handles tasks, notes, knowledge, contacts,
hub** meetings, decisions, processes, releases, and time. No
external tool required for core productivity.
**G2 - Hierarchy Everything has a clear home in the Domain \> Area \>
clarity** Project hierarchy. Navigation is always obvious.
**G3 - Time The system surfaces overcommitment before it happens,
sovereignty** not after. Time estimates, budgets, and tracking are
first-class.
**G4 - Knowledge Every significant decision, meeting outcome, and
capture** process is documented and findable. Organizational
knowledge accumulates over time.
**G5 - AI The system is designed for AI interaction from day
leverage** one. Any capable AI model can read, create, and update
any entity via the MCP interface.
**G6 - The architecture uses portable, standard technologies
Longevity** with no vendor lock-in. The system should still be
running and maintainable in 10 years.
**G7 - Speed** Common actions (capture, task create, status update,
search) require the minimum possible steps. Friction
is the enemy of adoption.
**G8 - Single-user system. Uptime and data safety matter more
Reliability** than scale. Logical deletes protect all data. Backups
are automated.
---------------- ------------------------------------------------------
**1.4 Design Principles**
- Hierarchy first. Everything belongs to a Domain. Areas and Projects
are optional groupings.
- KISS. Simple solutions chosen wherever functionality is equivalent.
Complexity must earn its place.
- Consistent patterns. Every list, form, and detail view follows
identical structural conventions. Learn once, apply everywhere.
- Logical deletes everywhere. No data is permanently destroyed without
explicit admin action.
- Context travels with navigation. Drill-down pre-fills context into
all create actions.
- Search is first-class. Global search covers every entity from day
one.
- Generic over specific. Shared base code handles common operations.
Entity-specific code handles only genuinely unique business logic.
- Config-driven where possible. Menu structure, simple entities, and
form layouts are configuration - not code.
-----------------------------------------------------------------------
**2. Functional Requirements**
-----------------------------------------------------------------------
*Priority: Must = required for Phase 1. Should = high value, Phase 1 if
possible. Could = Phase 2/3.*
-----------------------------------------------------------------------
**2.1 Core Hierarchy**
-----------------------------------------------------------------------
------------ --------------------------------------------- -------------- -----------
**ID** **Requirement** **Priority** **Phase**
**FR-001** System shall support four-level hierarchy: **Must** Phase 1
Domain \> Area \> Project \> Tasks/Content
**FR-002** Content items (Tasks, Notes, Lists, Links, **Must** Phase 1
Files) shall attach at Domain, Area, or
Project level
**FR-003** All hierarchy items shall support soft delete **Must** Phase 1
with recovery via Admin \> Trash
**FR-004** All list views shall support filter, sort, **Must** Phase 1
search, and drag-to-reorder
**FR-005** Sidebar shall support status filtering, text **Must** Phase 1
search, and smart auto-collapse
**FR-006** Breadcrumb navigation shall appear on all **Must** Phase 1
detail views
------------ --------------------------------------------- -------------- -----------
-----------------------------------------------------------------------
**2.2 Task Management**
-----------------------------------------------------------------------
------------ --------------------------------------------- -------------- -----------
**ID** **Requirement** **Priority** **Phase**
**FR-010** Tasks shall support priority (1-4), status, **Must** Phase 1
context, tags, due date, deadline,
recurrence, estimate, energy level
**FR-011** Tasks shall support subtasks via parent_id **Must** Phase 1
self-reference
**FR-012** Tasks shall support dependencies with full **Must** Phase 1
DAG (FS, FF, SS; SF via Admin)
**FR-013** Dependency cycle detection shall run on **Must** Phase 1
creation and reject circular dependencies
**FR-014** Status cascade shall automatically update **Must** Phase 1
dependent task statuses on blocker completion
**FR-015** Task list shall display in compact density **Must** Phase 1
(one row per task, all metadata inline)
**FR-016** Bulk actions shall be available: mark done, **Must** Phase 1
move, delete, add to focus
**FR-017** Quick add inline input shall appear at top of **Must** Phase 1
every task list
**FR-018** Waiting for / delegated field shall link task **Must** Phase 1
to a Contact with auto follow-up reminder
**FR-019** Task templates shall allow reusable **Must** Phase 1
blueprints with subtask checklists
**FR-020** Overdue tasks shall have distinct visual **Must** Phase 1
treatment (red date + left border)
------------ --------------------------------------------- -------------- -----------
-----------------------------------------------------------------------
**2.3 Daily Focus and Time Management**
-----------------------------------------------------------------------
------------ --------------------------------------------- -------------- -----------
**ID** **Requirement** **Priority** **Phase**
**FR-030** Daily focus list shall be date-scoped and **Must** Phase 1
orderable by drag. Position is the priority
signal.
**FR-031** Time estimates (minutes) shall be settable on **Must** Phase 1
tasks
**FR-032** Time tracking shall support start/stop timer **Must** Phase 1
per task, with running timer visible in
topbar
**FR-033** Time budgets per domain (weekly hours target) **Must** Phase 1
shall surface overcommitment on dashboard
**FR-034** Time blocks shall reserve calendar slots with **Must** Phase 1
context and energy level
**FR-035** Eisenhower Matrix view shall derive from **Must** Phase 1
existing priority and due date data
**FR-036** Dashboard shall show estimated hours in focus **Should** Phase 1
vs available time for the day
**FR-037** Weekly review built-in process template shall **Should** Phase 1
be provided at first setup
------------ --------------------------------------------- -------------- -----------
-----------------------------------------------------------------------
**2.4 Knowledge Management**
-----------------------------------------------------------------------
------------ --------------------------------------------- -------------- -----------
**ID** **Requirement** **Priority** **Phase**
**FR-040** Notes shall support rich text with inline **Must** Phase 1
wiki-style linking via \[\[ syntax
**FR-041** Notes shall be organizable in recursive **Must** Phase 1
folders with one folder per note
**FR-042** Notes shall support M2M project associations **Must** Phase 1
with is_primary flag
**FR-043** Meeting notes shall be toggled off by default **Must** Phase 1
in the Notes view
**FR-044** Decisions shall be a first-class entity **Must** Phase 1
linked to projects, contacts, and optionally
meetings
**FR-045** Decisions shall support superseded_by **Must** Phase 1
self-reference and status lifecycle
**FR-046** File preview shall display images and PDFs **Must** Phase 1
inline without downloading
**FR-047** Note version history shall record previous **Could** Phase 2
body states
------------ --------------------------------------------- -------------- -----------
-----------------------------------------------------------------------
**2.5 Meetings, Contacts, CRM**
-----------------------------------------------------------------------
------------ --------------------------------------------- -------------- -----------
**ID** **Requirement** **Priority** **Phase**
**FR-050** Meetings shall support agenda, transcript, **Must** Phase 1
rich text notes, action items, attendees,
decisions
**FR-051** Action items in meetings shall convert to **Must** Phase 1
tasks with one click, retaining meeting link
**FR-052** Meeting series shall use parent_id **Must** Phase 1
self-reference on the meetings table
**FR-053** Contacts shall associate to tasks, projects, **Must** Phase 1
lists, appointments, meetings with role field
**FR-054** Follow-up reminders per contact shall surface **Must** Phase 1
in dashboard and as sidebar badge
**FR-055** Pipeline / deal stages for CRM shall be **Could** Phase 2
supported
------------ --------------------------------------------- -------------- -----------
-----------------------------------------------------------------------
**2.6 Processes and Releases**
-----------------------------------------------------------------------
------------ --------------------------------------------- -------------- -----------
**ID** **Requirement** **Priority** **Phase**
**FR-060** Processes shall be typed as workflow **Must** Phase 1
(sequential, enforced) or checklist (any
order)
**FR-061** Process runs shall copy step content at **Must** Phase 1
creation. Template changes do not affect
active runs.
**FR-062** Process runs shall support all_at_once or **Must** Phase 1
step_by_step task generation modes
**FR-063** Releases shall be a system-level entity with **Must** Phase 1
M2M associations to multiple projects
**FR-064** Tasks shall optionally be tagged to a **Must** Phase 1
release. Untagged tasks form the project
backlog.
**FR-065** Milestones shall attach to a release or **Must** Phase 1
project with a target date and completion
state
**FR-066** Release detail shall show aggregate progress **Must** Phase 1
across all associated projects
------------ --------------------------------------------- -------------- -----------
-----------------------------------------------------------------------
**2.7 Search, Capture, Admin**
-----------------------------------------------------------------------
------------ --------------------------------------------- -------------- -----------
**ID** **Requirement** **Priority** **Phase**
**FR-070** Global search (Cmd/K) shall cover every **Must** Phase 1
entity with results grouped by type
**FR-071** Scoped search shall default to current **Must** Phase 1
project context, expandable to global
**FR-072** Capture bar shall accept multi-line paste and **Must** Phase 1
auto-parse into individual items
**FR-073** Capture items shall be convertible to any **Must** Phase 1
entity type
**FR-074** Context-aware capture shall pre-fill **Must** Phase 1
domain/project when opened within a project
**FR-075** Admin Trash shall show all soft-deleted items **Must** Phase 1
with restore and permanent delete
**FR-076** CSV export shall be available for tasks, **Must** Phase 1
projects, contacts, decisions
**FR-077** Personal dashboard metrics widget shall show **Must** Phase 1
weekly/monthly completion stats
**FR-078** AI MCP server shall expose all entities to AI **Must** Phase 2
models via MCP and OpenAI function format
**FR-079** Browser extension shall capture current page **Could** Phase 2
as weblink or capture item
------------ --------------------------------------------- -------------- -----------
-----------------------------------------------------------------------
**3. Non-Functional Requirements**
-----------------------------------------------------------------------
------------------- ------------------------------------------------------
**NFR-01 Page load under 500ms for standard views on local
Performance** network. Search results within 300ms. Timer updates in
real time.
**NFR-02 Target 99.5% uptime. Docker restart policy: always.
Reliability** Automated daily database backup to /opt/lifeos/backups
with 30-day retention.
**NFR-03 Data Logical deletes on all entities. No data permanently
Safety** destroyed without two-step admin confirmation.
PostgreSQL WAL enabled.
**NFR-04 No vendor lock-in. Standard PostgreSQL schema.
Portability** Standard Python. File storage on local filesystem.
Migratable to any Linux host.
**NFR-05 Generic base architecture reduces duplication.
Maintainability** Config-driven entities require zero code for new
simple entities. All routers follow identical
patterns.
**NFR-06 Security** Single-user, self-hosted. API key authentication for
MCP. Environment variables for all secrets. Never
committed to git. HTTPS enforced.
**NFR-07 Every common action reachable in 3 clicks or fewer.
Usability** Capture reachable in 1 click from anywhere. Search
reachable via keyboard shortcut always.
**NFR-08 Mobile** Bottom tab bar navigation. All core views usable on
phone. Swipe actions in Phase 3.
**NFR-09 Single-user system. No scale requirements. Design
Scalability** supports tens of thousands of records without
degradation via proper indexing.
**NFR-10 Application logs to stdout, captured by Docker. Error
Observability** logging with stack traces. Nginx access logs retained
7 days.
------------------- ------------------------------------------------------
-----------------------------------------------------------------------
**4. System Architecture Overview**
-----------------------------------------------------------------------
**4.1 High-Level Architecture**
+-----------------------------------------------------------------------+
| **Architecture Style** |
| |
| Server-rendered monolith with a config-driven generic core. No SPA, |
| no build pipeline, no microservices. Intentionally simple stack |
| chosen for longevity and maintainability. |
+-----------------------------------------------------------------------+
> ┌─────────────────────────────────────────────────────────┐
>
> │ CLIENTS │
>
> │ Browser (desktop) Browser (mobile) AI Models │
>
> └────────────┬────────────────┬───────────────┬───────────┘
>
> │ │ │
>
> ▼ ▼ ▼
>
> ┌─────────────────────────────────────────────────────────┐
>
> │ NGINX (defiant-01) │
>
> │ SSL termination · routing · static files · rate limit │
>
> │ lifeos.invixiom.com → lifeos-prod:8002 │
>
> │ lifeos-dev.invixiom.com → lifeos-dev:8003 │
>
> │ /ai/\* → lifeos-mcp:8004 \[Phase 2\] │
>
> └──────────────────────┬──────────────────────────────────┘
>
> │
>
> ┌───────────────┼───────────────┐
>
> ▼ ▼ ▼
>
> lifeos-prod lifeos-dev lifeos-mcp
>
> FastAPI:8002 FastAPI:8003 MCP Server:8004
>
> (production) (development) \[Phase 2\]
>
> │ │ │
>
> └───────────────┴───────────────┘
>
> │
>
> ▼
>
> ┌─────────────────┐
>
> │ lifeos-db │
>
> │ PostgreSQL 16 │
>
> │ lifeos_prod │
>
> │ lifeos_dev │
>
> └─────────────────┘
>
> │
>
> ┌────────┴────────┐
>
> ▼ ▼
>
> /opt/lifeos/ /opt/lifeos/
>
> files/prod/ files/dev/
>
> (file storage) (file storage)
**4.2 Request Flow**
> Browser request (HTTPS)
>
> → Nginx: SSL termination, domain routing
>
> → FastAPI route handler
>
> → Config resolution (entity type, field definitions)
>
> → BaseRepository or EntityRepository (SQLAlchemy async)
>
> → PostgreSQL (query execution)
>
> → Jinja2 template render (server-side HTML)
>
> → HTML response → browser
Form submissions use standard HTML POST. JavaScript handles only UI
interactions: sidebar collapse state, search modal, theme toggle, timer
display, markdown preview, drag-to-reorder. No fetch/XHR to backend from
JS.
**4.3 Docker Network Topology**
> Network: lifeos_network (bridge)
>
> Container Image Ports Volumes
>
> ─────────────────────────────────────────────────────────────────
>
> lifeos-db postgres:16-alpine 5432 (internal) pg_data
>
> lifeos-prod lifeos-app:latest 8002 (internal) files/prod
>
> lifeos-dev lifeos-app:latest 8003 (internal) files/dev
>
> lifeos-mcp lifeos-mcp:latest 8004 (internal) \[Phase 2\]
All container ports are internal to the Docker network. Only Nginx is
exposed to the public internet (ports 80, 443).
-----------------------------------------------------------------------
**5. Subsystems and Capabilities**
-----------------------------------------------------------------------
Life OS is composed of nine subsystems. Each subsystem is a coherent
capability domain with its own entities, views, and business logic. All
subsystems share the generic code base, data architecture, search, and
AI interface.
--------------- ------------------- ---------------------------------------
**Subsystem** **Primary **Key Capabilities**
Entities**
CRM contacts, Contact directory with roles,
appointments, appointment scheduling, follow-up
reminders reminders linked to contacts,
task/meeting/project associations with
role field
Project projects, releases, Full project lifecycle, releases
Management milestones, tasks, spanning multiple projects, milestone
dependencies tracking, DAG dependencies with cycle
detection and status cascade, progress
calculation
Task Management tasks, Priority/status/context, subtasks,
task_templates, dependencies, templates, time estimates
daily_focus, and tracking, Eisenhower matrix view,
time_entries daily focus with timer
Knowledge notes, Rich text notes with wiki-linking,
Management note_folders, recursive folders, decision knowledge
note_links, base with supersession chain, file
decisions, files, management with preview
links
Meeting meetings, decisions Full meeting records with
Management agenda/transcript/notes, action item
conversion, attendee management, series
support, decision capture
Process processes, Workflow vs checklist distinction,
Management process_steps, reusable templates, runs with snapshot
process_runs, isolation, task generation (all-at-once
process_run_steps or step-by-step)
Time Management time_entries, Time tracking per task, calendar time
time_blocks, blocking, domain weekly budgets,
time_budgets overcommitment surfacing, Eisenhower
matrix
Personal capture, Capture queue with multi-line parse,
Productivity daily_focus, GTD context types, daily focus, weekly
context_types review process, personal metrics
dashboard
Weblinks and weblinks, Organized bookmark system, recursive
Bookmarks weblink_folders folders, auto-generated project
folders, browser extension in Phase 2
--------------- ------------------- ---------------------------------------
**5.1 Subsystem Interaction Map**
> Tasks ←──────── Projects ←─── Releases
>
> │ │ │
>
> ├── Contacts ├── Processes ├── Milestones
>
> │ (waiting) │ (run tasks) │
>
> ├── Time ├── Notes └── Projects (M2M)
>
> │ Entries │ (M2M)
>
> ├── Daily ├── Decisions
>
> │ Focus │ (tabs)
>
> └── Dependencies └── Files
>
> (DAG) (polymorphic)
>
> Meetings ──── Decisions ──── Projects
>
> │ │
>
> ├── Contacts └── Contacts
>
> ├── Tasks (action items)
>
> └── Notes (auto-filed)
>
> Capture ──── any entity (polymorphic conversion)
>
> Search ──── every entity (full-text)
>
> MCP ──── every entity (Phase 2)
**5.2 Admin Subsystem**
- Trash: all soft-deleted items, grouped by entity type. Restore or
permanent delete.
- Context Types: manage GTD execution context lookup table.
- Dependency Settings: enable/disable start_to_finish dependency type.
- Export: CSV (Phase 1), JSON/PDF/Markdown (Phase 3).
- Model Registry: configure AI model connections (Phase 2).
- Theme: dark/light toggle (Phase 3).
- Storage: disk usage summary per domain.
-----------------------------------------------------------------------
**6. Data Architecture**
-----------------------------------------------------------------------
**6.1 Universal Column Conventions**
Every table without exception follows this field order and naming:
> id UUID PK DEFAULT gen_random_uuid()
>
> \[foreign keys\] nullable where optional
>
> \[content fields\] entity-specific
>
> tags TEXT\[\] nullable - flexible labels
>
> sort_order INT NOT NULL DEFAULT 0
>
> is_deleted BOOL NOT NULL DEFAULT false
>
> deleted_at TIMESTAMPTZ nullable
>
> created_at TIMESTAMPTZ NOT NULL DEFAULT now()
>
> updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+-----------------------------------------------------------------------+
| **Search Vector Convention** |
| |
| All searchable tables additionally carry: search_vector TSVECTOR. A |
| PostgreSQL trigger maintains this column automatically on |
| insert/update. A GIN index on search_vector enables fast full-text |
| queries. |
+-----------------------------------------------------------------------+
**6.2 Core Hierarchy Tables**
**domains**
----------------- ----------------- ----------------- -----------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
name TEXT No Work, Personal,
Business
color TEXT Yes Hex color #RRGGBB
sort_order INT No
is_deleted BOOL No
deleted_at TIMESTAMPTZ Yes
created_at TIMESTAMPTZ No
updated_at TIMESTAMPTZ No
----------------- ----------------- ----------------- -----------------
**areas**
----------------- ----------------- ----------------- -----------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
domain_id UUID No FK domains
CASCADE
name TEXT No
description TEXT Yes
sort_order INT No
is_deleted BOOL No
deleted_at TIMESTAMPTZ Yes
created_at / TIMESTAMPTZ No
updated_at
----------------- ----------------- ----------------- -----------------
**projects**
----------------- ----------------- ----------------- --------------------------------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
domain_id UUID No FK domains
area_id UUID Yes FK areas (optional grouping)
name TEXT No
description TEXT Yes
status TEXT No active\|on_hold\|completed\|archived
due_date DATE Yes
tags TEXT\[\] Yes
sort_order INT No
is_deleted BOOL No
deleted_at TIMESTAMPTZ Yes
created_at / TIMESTAMPTZ No
updated_at
----------------- ----------------- ----------------- --------------------------------------
**tasks**
------------------------ ----------------- ----------------- ---------------------------------------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
domain_id UUID Yes FK domains
area_id UUID Yes FK areas
project_id UUID Yes FK projects (null=standalone)
release_id UUID Yes FK releases (null=backlog)
parent_id UUID Yes Self-ref for subtasks
title TEXT No
description TEXT Yes
priority INT No 1=critical 2=high 3=normal 4=low
status TEXT No open\|in_progress\|blocked\|done\|cancelled
due_date DATE Yes Soft target
deadline TIMESTAMPTZ Yes Hard deadline
recurrence TEXT Yes null\|daily\|weekly\|monthly
estimated_minutes INT Yes Time estimate
energy_required TEXT Yes high\|medium\|low
context TEXT Yes FK context_types.value
is_custom_context BOOL Yes True if free-text context
waiting_for_contact_id UUID Yes FK contacts - delegated to
waiting_since DATE Yes Date delegation started
import_batch_id UUID Yes Groups bulk-imported tasks
tags TEXT\[\] Yes
sort_order INT No
is_deleted BOOL No
deleted_at TIMESTAMPTZ Yes
completed_at TIMESTAMPTZ Yes Set when status=done
created_at / updated_at TIMESTAMPTZ No
------------------------ ----------------- ----------------- ---------------------------------------------
**notes**
----------------- ----------------- ----------------- -----------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
domain_id UUID Yes FK domains
project_id UUID Yes FK projects
(primary project)
folder_id UUID Yes FK note_folders
(one folder)
meeting_id UUID Yes FK meetings if
meeting note
title TEXT No Required
body TEXT Yes Rich text content
content_format TEXT No Default: rich
is_meeting_note BOOL No Default false
tags TEXT\[\] Yes
sort_order INT No
is_deleted BOOL No
deleted_at TIMESTAMPTZ Yes
created_at / TIMESTAMPTZ No
updated_at
----------------- ----------------- ----------------- -----------------
**note_folders**
----------------- ----------------- ----------------- -----------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
parent_id UUID Yes Self-ref
recursive
name TEXT No
auto_generated BOOL No True for system
meeting folders
sort_order INT No
is_deleted BOOL No
created_at / TIMESTAMPTZ No
updated_at
----------------- ----------------- ----------------- -----------------
**lists and list_items**
----------------- ----------------- ----------------- -------------------------------
**Column** **Type** **Nullable** **Description**
id (lists) UUID No PK
domain_id UUID Yes FK domains
area_id UUID Yes FK areas
project_id UUID Yes FK projects
name TEXT No
list_type TEXT No checklist\|ordered\|unordered
description TEXT Yes
tags TEXT\[\] Yes
sort_order INT No
is_deleted BOOL No
\-\-- \-\-- \-\-- \-\-- list_items \-\--
id (list_items) UUID No PK
list_id UUID No FK lists
parent_item_id UUID Yes Self-ref for nested items
content TEXT No
completed BOOL No Default false
completed_at TIMESTAMPTZ Yes
sort_order INT No
is_deleted BOOL No
----------------- ----------------- ----------------- -------------------------------
**links and files**
------------------- ----------------- ----------------- ----------------------------------------
**Column** **Type** **Nullable** **Description**
id (links) UUID No PK
domain_id UUID Yes
project_id UUID Yes
label TEXT No Display name
url TEXT No Full URL
description TEXT Yes
sort_order INT No
is_deleted BOOL No
\-\-- \-\-- \-\-- \-\-- files \-\--
id (files) UUID No PK
filename TEXT No UUID-prefixed storage name
original_filename TEXT No User-facing name
storage_path TEXT No /opt/lifeos/files/{env}/{uuid}\_{name}
mime_type TEXT Yes
size_bytes INT Yes
description TEXT Yes
tags TEXT\[\] Yes
sort_order INT No
is_deleted BOOL No
------------------- ----------------- ----------------- ----------------------------------------
Files associate to entities via file_mappings junction (polymorphic). No
direct FK on the files table.
**6.3 System Level Tables**
**contacts**
----------------- ----------------- ----------------- -----------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
first_name TEXT No
last_name TEXT Yes
company TEXT Yes
role TEXT Yes Job title
email TEXT Yes
phone TEXT Yes
notes TEXT Yes Free text
tags TEXT\[\] Yes
sort_order INT No
is_deleted BOOL No
deleted_at TIMESTAMPTZ Yes
created_at / TIMESTAMPTZ No
updated_at
----------------- ----------------- ----------------- -----------------
**appointments**
----------------- ----------------- ----------------- ------------------------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
title TEXT No
start_at TIMESTAMPTZ No
end_at TIMESTAMPTZ Yes
all_day BOOL No Default false
location TEXT Yes
description TEXT Yes
recurrence TEXT Yes null\|daily\|weekly\|monthly
tags TEXT\[\] Yes
sort_order INT No
is_deleted BOOL No
created_at / TIMESTAMPTZ No
updated_at
----------------- ----------------- ----------------- ------------------------------
**meetings**
----------------- ----------------- ----------------- ---------------------------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
parent_id UUID Yes Self-ref: links instance to
series anchor
title TEXT No
meeting_date DATE No
start_at TIMESTAMPTZ Yes
end_at TIMESTAMPTZ Yes
location TEXT Yes Zoom, Google Meet, room name
status TEXT No scheduled\|completed\|cancelled
priority INT Yes 1=critical to 4=low
recurrence TEXT Yes For standing meetings
agenda TEXT Yes Rich text pre-meeting
transcript TEXT Yes Pasted from recording service
notes_body TEXT Yes Rich text during/post meeting
sort_order INT No Default sort: date desc
is_deleted BOOL No
deleted_at TIMESTAMPTZ Yes
created_at / TIMESTAMPTZ No
updated_at
----------------- ----------------- ----------------- ---------------------------------
**decisions**
------------------ ----------------- ----------------- ------------------------------------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
title TEXT No Summary of the decision
rationale TEXT Yes Full reasoning, rich text
status TEXT No proposed\|accepted\|rejected\|superseded
impact TEXT No low\|medium\|high
decided_at DATE Yes When decision was made (outside meeting
too)
meeting_id UUID Yes FK meetings (optional)
superseded_by_id UUID Yes Self-ref FK decisions
tags TEXT\[\] Yes
sort_order INT No
is_deleted BOOL No
deleted_at TIMESTAMPTZ Yes
created_at / TIMESTAMPTZ No
updated_at
------------------ ----------------- ----------------- ------------------------------------------
**releases and milestones**
----------------- ----------------- ----------------- -------------------------------------------
**Column** **Type** **Nullable** **Description**
id (releases) UUID No PK - System level, not under a project
name TEXT No Release 1.0, First Draft, Beta
version_label TEXT Yes 1.0.0, v2, Draft-1
description TEXT Yes
status TEXT No planned\|in_progress\|released\|cancelled
target_date DATE Yes
released_at DATE Yes Actual release date
release_notes TEXT Yes Rich text changelog
sort_order INT No
is_deleted BOOL No
deleted_at TIMESTAMPTZ Yes
created_at / TIMESTAMPTZ No
updated_at
\-\-- \-\-- \-\-- \-\-- milestones \-\--
id (milestones) UUID No PK
release_id UUID Yes FK releases (optional)
project_id UUID Yes FK projects (optional)
name TEXT No
target_date DATE No
completed_at DATE Yes
sort_order INT No
is_deleted BOOL No
----------------- ----------------- ----------------- -------------------------------------------
**processes, process_steps, process_runs, process_run_steps**
--------------------- ----------------- ----------------- ------------------------------------------------
**Column** **Type** **Nullable** **Description**
id (processes) UUID No PK
name TEXT No Publish a Book, Client Onboarding
description TEXT Yes
process_type TEXT No workflow\|checklist - key distinction
category TEXT Yes operational\|creative\|admin\|technical
status TEXT No draft\|active\|deprecated
tags TEXT\[\] Yes
\-\-- \-\-- \-\-- \-\-- process_steps \-\--
id (process_steps) UUID No PK
process_id UUID No FK processes
title TEXT No
instructions TEXT Yes Rich text
expected_output TEXT Yes
estimated_days INT Yes
context TEXT Yes FK context_types.value
sort_order INT No Sequential order
\-\-- \-\-- \-\-- \-\-- process_runs \-\--
id (process_runs) UUID No PK
process_id UUID No FK processes (source template)
title TEXT No Onboard ACME Corp - Mar 2026
status TEXT No not_started\|in_progress\|completed\|cancelled
process_type TEXT No Copied from template at run creation
task_generation TEXT No all_at_once\|step_by_step
project_id UUID Yes FK projects (optional context)
contact_id UUID Yes FK contacts (optional context)
started_at TIMESTAMPTZ Yes
completed_at TIMESTAMPTZ Yes
\-\-- \-\-- \-\-- \-\-- process_run_steps \-\--
id UUID No PK
(process_run_steps)
run_id UUID No FK process_runs
title TEXT No Copied from process_step - immutable
instructions TEXT Yes Copied from process_step - immutable
status TEXT No pending\|in_progress\|done\|skipped
completed_by_id UUID Yes FK contacts
completed_at TIMESTAMPTZ Yes
notes TEXT Yes
sort_order INT No
--------------------- ----------------- ----------------- ------------------------------------------------
**time management tables**
------------------ ----------------- ----------------- ----------------------------
**Column** **Type** **Nullable** **Description**
id (time_entries) UUID No PK
task_id UUID No FK tasks
start_at TIMESTAMPTZ No
end_at TIMESTAMPTZ Yes null if timer running
duration_minutes INT Yes Calculated on stop
notes TEXT Yes
is_deleted BOOL No
created_at TIMESTAMPTZ No
\-\-- \-\-- \-\-- \-\-- time_blocks \-\--
id (time_blocks) UUID No PK
task_id UUID Yes FK tasks (optional - block
can be contextual)
title TEXT No
context TEXT Yes deep_work\|meetings\|admin
energy TEXT Yes high\|medium\|low
start_at TIMESTAMPTZ No
end_at TIMESTAMPTZ No
is_deleted BOOL No
created_at / TIMESTAMPTZ No
updated_at
\-\-- \-\-- \-\-- \-\-- time_budgets \-\--
id (time_budgets) UUID No PK
domain_id UUID No FK domains
weekly_hours DECIMAL No Target hours per week
effective_from DATE No
is_deleted BOOL No
created_at TIMESTAMPTZ No
------------------ ----------------- ----------------- ----------------------------
**supporting system tables**
------------------- ----------------- ----------------- ----------------------------------------------------
**Column** **Type** **Nullable** **Description**
id (daily_focus) UUID No PK
focus_date DATE No
task_id UUID No FK tasks
slot INT Yes Display order - position is the priority signal
completed BOOL No Default false
note TEXT Yes
created_at TIMESTAMPTZ No
\-\-- \-\-- \-\-- \-\-- capture \-\--
id (capture) UUID No PK
raw_text TEXT No
processed BOOL No Default false
converted_to_type TEXT Yes task\|project\|note\|list\|contact\|decision\|link
converted_to_id UUID Yes Polymorphic FK
area_id UUID Yes Context at capture time
project_id UUID Yes Context at capture time
list_id UUID Yes Context at capture time
import_batch_id UUID Yes Groups multi-line paste imports
is_deleted BOOL No
created_at TIMESTAMPTZ No
\-\-- \-\-- \-\-- \-\-- task_templates \-\--
id (task_templates) UUID No PK
name TEXT No New Client Onboarding
description TEXT Yes
priority INT Yes Default priority
estimated_minutes INT Yes
energy_required TEXT Yes
context TEXT Yes
tags TEXT\[\] Yes
sort_order INT No
is_deleted BOOL No
\-\-- \-\-- \-\-- \-\-- task_template_items \-\--
id UUID No PK
template_id UUID No FK task_templates
title TEXT No
sort_order INT No
is_deleted BOOL No
------------------- ----------------- ----------------- ----------------------------------------------------
**weblinks, context_types, reminders**
------------------- ----------------- ----------------- -----------------------------------------------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
(weblink_folders)
parent_id UUID Yes Self-ref recursive
name TEXT No
auto_generated BOOL No True for system project folders
sort_order INT No
is_deleted BOOL No
\-\-- \-\-- \-\-- \-\-- weblinks \-\--
id (weblinks) UUID No PK
label TEXT No Display name
url TEXT No Full URL
description TEXT Yes
tags TEXT\[\] Yes
sort_order INT No
is_deleted BOOL No
\-\-- \-\-- \-\-- \-\-- context_types \-\--
id SERIAL No Integer PK (not UUID)
value TEXT No deep_work\|quick\|waiting\|someday\|meeting\|errand
label TEXT No Display label
is_system BOOL No True for built-in types
sort_order INT No
is_deleted BOOL No
\-\-- \-\-- \-\-- \-\-- reminders \-\--
id UUID No PK
entity_type TEXT No contact\|task\|meeting\|appointment
entity_id UUID No Polymorphic FK
remind_at TIMESTAMPTZ No When to surface
note TEXT Yes Follow up re: contract renewal
delivered BOOL No False until shown in UI
is_deleted BOOL No
created_at TIMESTAMPTZ No
------------------- ----------------- ----------------- -----------------------------------------------------
**6.4 Junction Tables**
---------------------- --------------------- -----------------------------------
**Junction Table** **Connects** **Key Columns**
note_projects notes \<-\> projects is_primary BOOL
note_links notes \<-\> notes source_note_id, target_note_id
(wiki graph)
file_mappings files \<-\> any context_type TEXT, context_id UUID
entity
release_projects releases \<-\> (no extra)
projects
release_domains releases \<-\> (no extra - optional context)
domains
contact_tasks contacts \<-\> tasks role TEXT
contact_projects contacts \<-\> role TEXT
projects
contact_lists contacts \<-\> lists role TEXT
contact_list_items contacts \<-\> role TEXT
list_items
contact_appointments contacts \<-\> role TEXT
appointments
contact_meetings contacts \<-\> role TEXT
meetings (organizer\|attendee\|optional)
decision_projects decisions \<-\> (no extra)
projects
decision_contacts decisions \<-\> role TEXT
contacts (proposer\|approver\|stakeholder)
meeting_tasks meetings \<-\> tasks source TEXT
(discussed\|action_item)
process_run_tasks process_run_steps run_step_id FK
\<-\> tasks
folder_weblinks weblink_folders \<-\> (no extra)
weblinks
---------------------- --------------------- -----------------------------------
**6.5 Dependencies Table**
One polymorphic table handles all dependency relationships across all
entity types. Full DAG support.
----------------- ----------------- ----------------- --------------------------------------------------------------------
**Column** **Type** **Nullable** **Description**
id UUID No PK
blocker_type TEXT No task\|project\|process_step\|process_run
blocker_id UUID No
dependent_type TEXT No task\|project\|process_step\|process_run
dependent_id UUID No
dependency_type TEXT No finish_to_start\|finish_to_finish\|start_to_start\|start_to_finish
lag_days INT No Default 0
note TEXT Yes
is_deleted BOOL No Default false
deleted_at TIMESTAMPTZ Yes
created_at TIMESTAMPTZ No Auto
----------------- ----------------- ----------------- --------------------------------------------------------------------
Indexes: idx_dependencies_blocker (blocker_type, blocker_id),
idx_dependencies_dependent (dependent_type, dependent_id)
Constraints: UNIQUE (blocker_type, blocker_id, dependent_type,
dependent_id, dependency_type), CHECK no self-dependency
**6.6 Complete Table Inventory (50 tables)**
------------------------ --------------------- -------------------------
**Table** **Category** **Phase**
domains Core hierarchy 1
areas Core hierarchy 1
projects Core hierarchy 1
tasks Core hierarchy 1
notes Core hierarchy 1
note_folders Core hierarchy 1
lists Core hierarchy 1
list_items Core hierarchy 1
links Core hierarchy 1
files Core hierarchy 1
contacts System level 1
appointments System level 1
meetings System level 1
decisions System level 1
releases System level 1
milestones System level 1
processes System level 1
process_steps System level 1
process_runs System level 1
process_run_steps System level 1
daily_focus System level 1
capture System level 1
task_templates System level 1
task_template_items System level 1
time_entries Time management 1
time_blocks Time management 1
time_budgets Time management 1
weblink_folders System level 1
weblinks System level 1
context_types Lookup 1
reminders System level 1
dependencies Universal junction 1
note_projects Junction 1
note_links Junction 1
file_mappings Junction 1
release_projects Junction 1
release_domains Junction 1
contact_tasks Junction 1
contact_projects Junction 1
contact_lists Junction 1
contact_list_items Junction 1
contact_appointments Junction 1
contact_meetings Junction 1
decision_projects Junction 1
decision_contacts Junction 1
meeting_tasks Junction 1
process_run_tasks Junction 1
folder_weblinks Junction 1
note_version_history Knowledge mgmt 2
pipelines CRM 2
------------------------ --------------------- -------------------------
-----------------------------------------------------------------------
**7. Application Layer Architecture**
-----------------------------------------------------------------------
**7.1 Technology Stack**
---------------- ------------------------------------------------------
**Language** Python 3.12
**Framework** FastAPI (async)
**ORM** SQLAlchemy 2.0 async + psycopg3
**Templates** Jinja2 (server-rendered HTML)
**Forms** Standard HTML POST, python-multipart
**Search** PostgreSQL tsvector/tsquery (no external service)
**File python-multipart, aiofiles
handling**
**Config** python-dotenv, YAML for entity/menu config
**Validation** Pydantic v2 models for request/response
**Testing** pytest-asyncio, httpx
---------------- ------------------------------------------------------
**7.2 Project File Structure**
> life-os/
>
> main.py FastAPI app init, middleware, router includes
>
> config/
>
> entities.yaml Config-driven entity definitions (12 simple entities)
>
> menu.yaml Sidebar navigation config
>
> search.yaml Searchable entities and field weights
>
> core/
>
> database.py Async engine, session factory
>
> base_repository.py BaseRepository:
> list/get/create/update/soft_delete/restore
>
> generic_router.py Config-driven CRUD router for simple entities
>
> generic_templates.py Template context builder for config-driven views
>
> search.py Global search implementation
>
> dependencies.py DAG cycle detection, status cascade
>
> reminders.py Reminder surfacing on dashboard load
>
> timer.py Time tracking start/stop logic
>
> routers/
>
> tasks.py Task CRUD + subtasks + templates + bulk actions
>
> projects.py Project CRUD + progress calculation
>
> releases.py Release CRUD + multi-project aggregation
>
> meetings.py Meeting CRUD + action items + series
>
> decisions.py Decision CRUD + supersession chain
>
> processes.py Template CRUD + run management + task generation
>
> capture.py Queue management + multi-line parse + conversion
>
> focus.py Daily focus list management
>
> notes.py Note CRUD + wiki links + folder management
>
> search.py Global search endpoint
>
> files.py Upload + download + preview routing
>
> calendar.py Unified calendar view (appointments + meetings + tasks)
>
> admin.py Trash + context types + settings + export
>
> dashboard.py Dashboard aggregation + metrics widget
>
> time.py Time entries + blocks + budget views
>
> eisenhower.py Matrix view derivation
>
> \[generic entities\] domains, areas, contacts, weblinks, etc via
> generic_router
>
> templates/
>
> base.html Shell: topbar, sidebar, JS includes, theme classes
>
> \_list.html Generic list template (all entities)
>
> \_detail.html Generic detail shell (tabs, breadcrumb, header)
>
> \_form.html Generic create/edit form
>
> \_empty.html Generic empty state component
>
> dashboard.html Dashboard with widgets
>
> focus.html Daily focus view
>
> tasks.html Task list (extends \_list.html)
>
> task_detail.html Task detail with dependencies panel
>
> project_detail.html Project detail with tabs
>
> release_detail.html Release detail with multi-project view
>
> meeting_detail.html Meeting detail with action items
>
> process_detail.html Process template + runs
>
> note_detail.html Note editor with wiki link support
>
> calendar.html Calendar view
>
> eisenhower.html Eisenhower matrix view
>
> capture_queue.html Capture review and convert
>
> admin_trash.html Trash recovery view
>
> search_results.html Global search results
>
> static/
>
> style.css All styles (dark theme, light theme, components)
>
> app.js Sidebar collapse, search modal, timer, theme toggle
>
> sortable.js Drag-to-reorder (SortableJS CDN or local)
>
> requirements.txt
>
> .env NEVER committed to git
>
> docker-compose.yml
**7.3 Router Anatomy**
All routers follow this identical pattern regardless of entity
complexity:
> from fastapi import APIRouter, Request, Form, Depends
>
> from core.base_repository import BaseRepository
>
> from core.database import get_db
>
> router = APIRouter(prefix=\'/tasks\', tags=\[\'tasks\'\])
>
> templates = Jinja2Templates(directory=\'templates\')
>
> \@router.get(\'/\')
>
> async def list_tasks(request: Request, db=Depends(get_db),
> \...filters):
>
> repo = TaskRepository(db)
>
> items = await repo.list(filters=filters, sort=sort)
>
> sidebar = await get_sidebar_data(db)
>
> return templates.TemplateResponse(\'tasks.html\', {
>
> \'request\': request, \'items\': items, \'sidebar\': sidebar
>
> })
>
> \@router.post(\'/create\')
>
> async def create_task(request: Request, db=Depends(get_db),
> \...fields):
>
> repo = TaskRepository(db)
>
> task = await repo.create({\...fields})
>
> return RedirectResponse(url=f\'/tasks/{task.id}\', status_code=303)
-----------------------------------------------------------------------
**8. Generic Code Architecture**
-----------------------------------------------------------------------
The generic architecture reduces code volume by 40-45% and ensures
consistency across all entities. Three layers work together:
BaseRepository handles all common data operations, config-driven
entities eliminate entity-specific code entirely for simple entities,
and the menu/sidebar is fully configuration-driven.
**8.1 Entity Classification**
-------------------- ------------------------ ------------------------------
**Classification** **Entities** **Approach**
Fully config-driven domains, areas, entities.yaml config +
(zero custom code) context_types, weblinks, generic_router.py +
weblink_folders, \_list.html + \_form.html
note_folders,
time_budgets,
task_templates,
task_template_items,
milestones,
release_domains,
release_projects
Generic base + contacts, appointments, BaseRepository extended with
overrides notes, links, files, custom methods. Standard
meetings, decisions, templates with entity-specific
releases, processes, blocks.
process_steps,
list_items, lists,
time_blocks,
time_entries, reminders,
note_links,
file_mappings
Substantially custom tasks, projects, Full custom router.
logic process_runs, BaseRepository as foundation.
process_run_steps, Business logic in dedicated
daily_focus, capture, service classes.
dependencies, search,
releases (aggregate),
task_templates
(instantiate), all
contact junction tables
-------------------- ------------------------ ------------------------------
**8.2 BaseRepository**
> class BaseRepository:
>
> def \_\_init\_\_(self, table: str, db: AsyncSession):
>
> self.table = table
>
> self.db = db
>
> async def list(self, filters={}, sort=\'sort_order\',
>
> page=1, per_page=50) -\> list:
>
> \# Adds WHERE is_deleted=false automatically
>
> \# Applies filter dict as WHERE clauses
>
> \# Applies sort with fallback to created_at
>
> async def get(self, id: UUID) -\> dict \| None:
>
> async def create(self, data: dict) -\> dict:
>
> \# Auto-sets created_at, updated_at, is_deleted=false
>
> \# Updates search_vector via trigger
>
> async def update(self, id: UUID, data: dict) -\> dict:
>
> \# Auto-sets updated_at
>
> async def soft_delete(self, id: UUID) -\> dict:
>
> \# Sets is_deleted=true, deleted_at=now()
>
> async def restore(self, id: UUID) -\> dict:
>
> \# Sets is_deleted=false, deleted_at=null
>
> async def bulk_soft_delete(self, ids: list\[UUID\]) -\> int:
>
> async def list_deleted(self) -\> list:
>
> \# Used by Admin \> Trash
>
> async def permanent_delete(self, id: UUID) -\> bool:
>
> \# Actual SQL DELETE - Admin only
**8.3 Config-Driven Entity Definition**
> \# config/entities.yaml
>
> domains:
>
> table: domains
>
> display_name: Domain
>
> display_plural: Domains
>
> icon: grid
>
> fields:
>
> \- name: name type: text required: true label: Domain Name
>
> \- name: color type: color required: false label: Color
>
> list_columns: \[name, color, created_at\]
>
> searchable: \[name\]
>
> sort_default: sort_order
>
> allow_reorder: true
>
> contacts:
>
> table: contacts
>
> display_name: Contact
>
> fields:
>
> \- name: first_name type: text required: true
>
> \- name: last_name type: text
>
> \- name: company type: text
>
> \- name: email type: email
>
> \- name: phone type: tel
>
> \- name: notes type: textarea
>
> \- name: tags type: tags
>
> list_columns: \[first_name, last_name, company, email\]
>
> searchable: \[first_name, last_name, company, email\]
**8.4 Config-Driven Sidebar**
> \# config/menu.yaml
>
> system_items:
>
> \- id: dashboard label: Dashboard icon: grid route: /
>
> \- id: focus label: Focus icon: target route: /focus badge:
> focus_count
>
> \- id: tasks label: All Tasks icon: check route: /tasks
>
> \- id: calendar label: Calendar icon: calendar route: /calendar
>
> \- id: meetings label: Meetings icon: users route: /meetings
>
> \- id: decisions label: Decisions icon: diamond route: /decisions
>
> \- id: releases label: Releases icon: tag route: /releases
>
> \- id: processes label: Processes icon: flow route: /processes
>
> \- id: notes label: Notes icon: file route: /notes
>
> \- id: contacts label: Contacts icon: person route: /contacts
>
> \- id: weblinks label: Weblinks icon: link route: /weblinks
>
> \- id: capture label: Capture icon: inbox route: /capture badge:
> capture_count
>
> \- id: admin label: Admin icon: settings route: /admin
>
> mobile_bottom_bar:
>
> \- id: dashboard icon: grid label: Home
>
> \- id: focus icon: target label: Focus
>
> \- id: tasks icon: check label: Tasks
>
> \- id: calendar icon: calendar label: Calendar
>
> \- id: more icon: menu label: More
>
> mobile_more_items: \[meetings, decisions, contacts, processes,
> weblinks, admin\]
-----------------------------------------------------------------------
**9. Frontend Architecture**
-----------------------------------------------------------------------
**9.1 Approach**
Server-rendered HTML via Jinja2 templates. No frontend framework, no
build pipeline, no npm. CSS custom properties for theming. Vanilla JS
for UI interactions only. SortableJS for drag-to-reorder (single
dependency).
**9.2 Design Tokens**
> /\* style.css - CSS custom properties \*/
>
> \[data-theme=\'dark\'\] {
>
> \--bg: #0D0E13; \--surface: #14161F;
>
> \--surface2: #1A1D28; \--border: #252836;
>
> \--text: #DDE1F5; \--muted: #5A6080;
>
> \--accent: #4F6EF7; \--accent-soft:rgba(79,110,247,.12);
>
> \--green: #22C98A; \--amber: #F5A623;
>
> \--red: #F05252; \--purple: #9B7FF5;
>
> }
>
> \[data-theme=\'light\'\] {
>
> \--bg: #F0F2F8; \--surface: #FFFFFF;
>
> \--surface2: #F7F8FC; \--border: #E3E6F0;
>
> \--text: #171926; \--muted: #8892B0;
>
> \--accent: #4F6EF7; \--accent-soft:rgba(79,110,247,.10);
>
> \--green: #10B981; \--amber: #F59E0B;
>
> \--red: #DC2626;
>
> }
**9.3 Universal Layout Patterns**
**These patterns apply identically to every screen. Learn once, apply
everywhere.**
-----------------------------------------------------------------------
**Every list view**
-----------------------------------------------------------------------
> \[Page title + count\] \[+ Add button\]
>
> \[Filter chips: Status / Domain / Priority\] \[Sort dropdown\]
>
> \[Search within this view input\]
>
> ─────────────────────────────────────────────────────────
>
> \[Row\] \[check\] \[pri\] \[Title\...\...\...\...\] \[tag\] \[proj\]
> \[date\]
>
> \[Row\] \[check\] \[pri\] \[Title\...\...\...\...\] \[tag\] \[proj\]
> \[date\]
>
> \[Empty state with CTA if no items\]
-----------------------------------------------------------------------
**Every detail view**
-----------------------------------------------------------------------
> \[Breadcrumb: Domain \> Area \> Project \> Item\]
>
> \[Header: name, metadata, progress bar if applicable\]
>
> \[Tabs: Tasks \| Notes \| Lists \| Links \| Files \| Contacts \|
> Decisions\]
>
> ─────────────────────────────────────────────────────────
>
> \[Tab content: same list pattern as above\]
-----------------------------------------------------------------------
**Three action levels - always same position**
-----------------------------------------------------------------------
- Row level: hover shows quick actions right-aligned (complete, edit,
delete)
- Selection level: checkbox selects reveal bulk action bar at top
- Page level: + Add button top right, always visible
**9.4 Component Library**
----------------- ---------------------- ---------------------------------
**Component** **Description** **Used in**
list-row Compact task/item row All list views
with check, pri dot,
title, meta
filter-chip Toggleable filter All list views
button with active
state
sort-dropdown Sort selector with All list views
current sort shown
entity-header Name, metadata, All detail views
progress bar, status
badge
tab-strip Horizontal tab All detail views
navigation with active
state
related-widget Polymorphic attachment Detail views
list with + link
button
search-modal Full-screen search Global (Cmd/K)
overlay with grouped
results
toast Timed/dismissible Global
notification
(success/error/undo)
confirm-dialog Destructive action Delete actions
confirmation with item
name
timer-pill Running timer display Topbar
in topbar with stop
button
empty-state Illustrated All list views
placeholder with
guidance text and CTA
skeleton Grey placeholder All views
shapes for loading
state
wiki-link Inline \[\[ trigger Note editor
for note linking
file-preview Modal for File lists
image/PDF/video inline
preview
eisenhower-grid 2x2 matrix derived Tasks view
from priority +
urgency
----------------- ---------------------- ---------------------------------
**9.5 JavaScript Responsibilities**
JS handles only UI state. No data fetching from JS. No SPA routing.
- Sidebar collapse state (localStorage persistence per domain)
- Search modal open/close (Cmd/K trigger, Escape close)
- Theme toggle (data-theme attribute on html element, localStorage)
- Timer: start/stop, elapsed display, topbar pill update
- Drag-to-reorder via SortableJS, POST to /reorder endpoint on drop
- File preview modal open/close
- Wiki link \[\[ autocomplete dropdown in note editor
- Capture multi-line paste detection and line count preview
- Toast auto-dismiss timer
- Confirm dialog show/hide
- Sidebar filter toggle per domain
-----------------------------------------------------------------------
**10. Infrastructure Architecture**
-----------------------------------------------------------------------
**10.1 Server**
---------------- ------------------------------------------------------
**Host** defiant-01
**IP** 46.225.166.142
**OS** Ubuntu 24.04 LTS
**CPU / RAM** As provisioned by hosting provider
**Docker** Docker Engine + docker-compose v2
**DNS A record** lifeos.invixiom.com -\> 46.225.166.142
**DNS A record** lifeos-dev.invixiom.com -\> 46.225.166.142
---------------- ------------------------------------------------------
**10.2 Docker Compose Configuration**
> version: \'3.9\'
>
> services:
>
> lifeos-db:
>
> image: postgres:16-alpine
>
> container_name: lifeos-db
>
> restart: unless-stopped
>
> environment:
>
> POSTGRES_USER: lifeos_dev
>
> POSTGRES_PASSWORD: \${DB_PASSWORD}
>
> volumes:
>
> \- pg_data:/var/lib/postgresql/data
>
> networks: \[lifeos_network\]
>
> lifeos-prod:
>
> build: .
>
> container_name: lifeos-prod
>
> restart: unless-stopped
>
> environment:
>
> DATABASE_URL:
> postgresql+asyncpg://lifeos_dev:\${DB_PASSWORD}@lifeos-db/lifeos_prod
>
> FILE_STORAGE_PATH: /opt/lifeos/files/prod
>
> ENVIRONMENT: production
>
> MCP_API_KEY: \${MCP_API_KEY}
>
> volumes:
>
> \- /opt/lifeos/files/prod:/opt/lifeos/files/prod
>
> networks: \[lifeos_network\]
>
> depends_on: \[lifeos-db\]
>
> lifeos-dev:
>
> build: .
>
> container_name: lifeos-dev
>
> restart: unless-stopped
>
> environment:
>
> DATABASE_URL:
> postgresql+asyncpg://lifeos_dev:\${DB_PASSWORD}@lifeos-db/lifeos_dev
>
> FILE_STORAGE_PATH: /opt/lifeos/files/dev
>
> ENVIRONMENT: development
>
> volumes:
>
> \- /opt/lifeos/files/dev:/opt/lifeos/files/dev
>
> \- ./:/app \# hot reload in dev
>
> networks: \[lifeos_network\]
>
> depends_on: \[lifeos-db\]
>
> \# Phase 2:
>
> \# lifeos-mcp:
>
> \# build: ./mcp
>
> \# container_name: lifeos-mcp
>
> \# environment:
>
> \# LIFEOS_API_URL: http://lifeos-prod:8002
>
> \# MCP_API_KEY: \${MCP_API_KEY}
>
> \# networks: \[lifeos_network\]
>
> volumes:
>
> pg_data:
>
> networks:
>
> lifeos_network:
>
> external: true
**10.3 Nginx Configuration**
> \# /etc/nginx/sites-available/lifeos
>
> \# HTTP -\> HTTPS redirect
>
> server {
>
> listen 80;
>
> server_name lifeos.invixiom.com lifeos-dev.invixiom.com;
>
> return 301 https://\$host\$request_uri;
>
> }
>
> \# Production
>
> server {
>
> listen 443 ssl;
>
> server_name lifeos.invixiom.com;
>
> ssl_certificate
> /etc/letsencrypt/live/lifeos.invixiom.com/fullchain.pem;
>
> ssl_certificate_key
> /etc/letsencrypt/live/lifeos.invixiom.com/privkey.pem;
>
> client_max_body_size 100M;
>
> location /static/ { alias /opt/lifeos/static/; }
>
> location /files/ {
>
> alias /opt/lifeos/files/prod/;
>
> internal; \# served only via X-Accel-Redirect from FastAPI
>
> }
>
> \# Phase 2: AI gateway
>
> \# location /ai/ { proxy_pass http://lifeos-mcp:8004/; }
>
> location / {
>
> proxy_pass http://lifeos-prod:8002;
>
> proxy_set_header Host \$host;
>
> proxy_set_header X-Real-IP \$remote_addr;
>
> }
>
> }
>
> \# Development (same structure, port 8003, lifeos-dev)
**10.4 Database Management**
-----------------------------------------------------------------------
**Backups**
-----------------------------------------------------------------------
> \# Daily automated backup - cron job
>
> 0 3 \* \* \* docker exec lifeos-db pg_dump -U lifeos_dev lifeos_prod
> \| \\
>
> gzip \> /opt/lifeos/backups/prod\_\$(date +%Y%m%d).sql.gz
>
> \# Retention: 30 days
>
> find /opt/lifeos/backups -name \'prod\_\*.sql.gz\' -mtime +30 -delete
-----------------------------------------------------------------------
**Migrations**
-----------------------------------------------------------------------
- Schema changes applied via numbered SQL migration files:
/opt/lifeos/migrations/
- Applied manually via psql inside lifeos-db container
- Migration log table tracks applied migrations
- Always apply to lifeos_dev first, verify, then apply to lifeos_prod
**10.5 Directory Structure on defiant-01**
> /opt/lifeos/
>
> backups/ Daily pg_dump archives (30-day retention)
>
> files/
>
> prod/ Production file uploads
>
> dev/ Development file uploads
>
> migrations/ Numbered SQL migration files
>
> static/ Shared static assets (CSS, JS)
>
> lifeos-setup.sh Repeatable server setup script
>
> .env Environment variables (never in git)
>
> docker-compose.yml Container definitions
>
> /var/log/nginx/
>
> lifeos_access.log 7-day retention
>
> lifeos_error.log
-----------------------------------------------------------------------
**11. Search Architecture**
-----------------------------------------------------------------------
**11.1 Implementation**
PostgreSQL native full-text search via tsvector/tsquery. No external
search service required. Fast at single-user scale.
> \-- Every searchable table gets:
>
> search_vector TSVECTOR
>
> \-- GIN index for fast queries:
>
> CREATE INDEX idx_tasks_search ON tasks USING GIN(search_vector);
>
> \-- Trigger maintains search_vector on insert/update:
>
> CREATE TRIGGER tasks_search_update
>
> BEFORE INSERT OR UPDATE ON tasks
>
> FOR EACH ROW EXECUTE FUNCTION
>
> tsvector_update_trigger(search_vector, \'pg_catalog.english\',
>
> \'title\', \'description\', \'tags\');
**11.2 Global Search Behavior**
- Triggered by Cmd/K from anywhere, or search icon in topbar
- 200ms debounce, instant results as you type
- Searches all entities in parallel async queries
- Results grouped by entity type, most relevant section first
- Every result shows full context path: Title -\> Project -\> Domain
- Recent searches shown before typing (last 10, localStorage)
- Filter within results by entity type, domain, date range, status
**11.3 Scoped Search**
- Default to current project/domain scope when inside a context
- One click or Cmd+Shift+K to expand to global scope
- Scope indicator shown in search bar placeholder text
**11.4 Searchable Entities**
tasks, projects, notes, lists, list_items, contacts, appointments,
meetings, decisions, processes, weblinks, files, capture, links,
releases, milestones
-----------------------------------------------------------------------
**12. Time Management Architecture**
-----------------------------------------------------------------------
**12.1 Components**
---------------- ---------------------- -------------------------------
**Component** **Purpose** **Data source**
Time estimates How long a task should User input at task create/edit
take
(estimated_minutes on
tasks)
Time tracking How long a task Start/stop timer per task
actually took
(time_entries table)
Time budgets Weekly hour targets User configures in Admin
per domain
(time_budgets table)
Time blocks Reserved calendar User creates on Calendar view
slots (time_blocks
table)
Eisenhower Importance vs urgency Derived from priority + due
Matrix view of current tasks date
Availability Open time after blocks Derived from calendar + blocks
view and appointments
Dashboard widget Today: Xh estimated vs Derived on load, cached 5min
Xh available
Weekly metrics Tasks done, hours Derived, aggregated on load
logged, meetings,
decisions
---------------- ---------------------- -------------------------------
**12.2 Timer Flow**
> User clicks timer button on task row
>
> -\> POST /time/start {task_id}
>
> -\> Creates time_entries row: start_at=now(), end_at=null
>
> -\> Returns entry_id
>
> -\> JS updates topbar timer pill with running indicator
>
> User clicks stop in topbar pill
>
> -\> POST /time/stop {entry_id}
>
> -\> Sets end_at=now(), calculates duration_minutes
>
> -\> Returns updated entry
>
> -\> Topbar pill clears
>
> -\> Task row shows updated total logged time
Only one timer can run at a time. Starting a new timer auto-stops any
running timer.
**12.3 Overcommitment Surfacing**
> Dashboard load:
>
> 1\. Get today\'s focus task list with estimated_minutes for each
>
> 2\. Sum estimated_minutes for open tasks -\> today_estimate
>
> 3\. Get time_blocks for today -\> available_hours
>
> 4\. Get time_budgets for each domain -\> weekly budget
>
> 5\. Sum estimated_minutes for all open tasks this week -\>
> week_estimate
>
> 6\. Compare: if week_estimate \> weekly_budget -\> show overcommitment
> warning
**12.4 Eisenhower Matrix Logic**
> For each open task:
>
> importance = priority (1=critical/2=high -\> Important)
>
> urgency = due_date proximity:
>
> overdue or due today/tomorrow -\> Urgent
>
> due within 7 days -\> Urgent
>
> due \> 7 days or no date -\> Not Urgent
>
> Quadrant assignment:
>
> Important + Urgent -\> Do First (red)
>
> Important + Not Urgent -\> Schedule (blue)
>
> Not Important + Urgent -\> Delegate (amber)
>
> Not Important + Not Urgent -\> Eliminate/Someday (grey)
Matrix is a derived view - no new data, just a different lens on
existing task fields. Rendered as a 2x2 grid with task counts per
quadrant. Clicking a quadrant opens the task list filtered to that
quadrant.
-----------------------------------------------------------------------
**13. AI and MCP Architecture (Phase 2)**
-----------------------------------------------------------------------
**13.1 Design Principle**
One tool implementation. Two transport formats. Any AI model. The MCP
server is a thin transport adapter over the shared tool core. Adding a
new model provider requires only a config entry.
**13.2 Architecture**
> ┌───────────────────────────────────────────────────────┐
>
> │ AI CLIENTS │
>
> │ Claude (MCP) GPT-4o (func) Mistral Ollama │
>
> └──────┬──────────────┬────────────────┬────────────────┘
>
> │ │ │
>
> MCP transport OpenAI format OpenAI format
>
> (stdio/SSE) (function call) (function call)
>
> │ │ │
>
> └──────────────┴────────────────┘
>
> │
>
> ┌────────────▼────────────┐
>
> │ lifeos-mcp:8004 │
>
> │ MCP Server Container │
>
> │ │
>
> │ /mcp (MCP transport) │
>
> │ /tools/openai (OAI fmt) │
>
> └────────────┬─────────────┘
>
> │ HTTP (Docker internal)
>
> ▼
>
> ┌────────────────────────┐
>
> │ Tool Core Layer │
>
> │ tools/tasks.py │
>
> │ tools/projects.py │
>
> │ tools/meetings.py │
>
> │ tools/search.py │
>
> │ tools/meta.py │
>
> │ \... (all entities) │
>
> └────────────┬────────────┘
>
> │ HTTP + API key
>
> ▼
>
> ┌────────────────────────┐
>
> │ lifeos-prod FastAPI │
>
> └────────────────────────┘
**13.3 Tool Inventory (46 tools)**
--------------- ---------------------------------------- ---------------
**Category** **Tools** **Count**
Context/Meta get_context (domains+areas+projects), 2
get_dashboard_summary
Tasks create, list, get, update, complete, 9
delete, add_to_focus, get_blocked,
list_dependencies
Projects create, list, get, update, get_progress, 6
list_tasks
Meetings create, list, get, add_note, 6
create_action_item, list_decisions
Decisions create, list, get, update, 5
link_to_project
Processes list, get, start_run, complete_step, 5
get_run_status
Notes create, list, get, update, search_notes 5
Contacts create, list, get, search_contacts 4
Capture create, list_unprocessed, process_item 3
Search search (global, all entities) 1
--------------- ---------------------------------------- ---------------
**13.4 Model Registry Configuration**
> \# config/ai_models.yaml (editable from Admin UI)
>
> models:
>
> personal:
>
> provider: anthropic
>
> model: claude-opus-4-6
>
> interface: mcp
>
> api_key_env: ANTHROPIC_API_KEY
>
> work:
>
> provider: openai
>
> model: gpt-4o
>
> interface: openai_functions
>
> api_key_env: OPENAI_API_KEY_WORK
>
> local:
>
> provider: ollama
>
> model: llama3
>
> interface: openai_functions
>
> base_url: http://localhost:11434
**13.5 Claude Desktop Connection**
> \# \~/Library/Application Support/Claude/claude_desktop_config.json
>
> {
>
> \"mcpServers\": {
>
> \"lifeos\": {
>
> \"command\": \"ssh\",
>
> \"args\": \[\"root@46.225.166.142\",
>
> \"docker exec -i lifeos-mcp python mcp_server.py\"\],
>
> \"env\": { \"MCP_API_KEY\": \"your-secret-key\" }
>
> }
>
> }
>
> }
-----------------------------------------------------------------------
**14. Security Architecture**
-----------------------------------------------------------------------
Single-user, self-hosted system. Security requirements are pragmatic,
not enterprise-grade. The primary threats are unauthorized external
access and accidental data loss.
------------- --------------------------- ------------------------------
**Layer** **Mechanism** **Notes**
Transport HTTPS enforced via Nginx + HTTP redirects to HTTPS
Let\'s Encrypt
Application No authentication in Phase Phase 3: basic auth or simple
access 1 (single user, private session login
server)
MCP/AI access Static API key (X-MCP-Key Rotate via .env, never in git
header) required for all
MCP calls
File access Files served via internal X-Accel-Redirect pattern
Nginx path, not public URL prevents directory traversal
Database PostgreSQL on internal Not exposed to public internet
Docker network only
Secrets All in .env file, never .gitignore enforced
committed
Data safety Logical deletes, no 30-day backup retention
destructive ops without
admin confirmation
Dependency SQLAlchemy sessions scoped No shared mutable state
injection per request
------------- --------------------------- ------------------------------
+-----------------------------------------------------------------------+
| **Phase 3 Authentication** |
| |
| If the application is ever exposed beyond the private server or |
| accessed by multiple users, add: HTTP basic auth as immediate |
| stopgap, then full session-based auth with Supabase Auth or a simple |
| JWT implementation. Row Level Security would need to be added to the |
| PostgreSQL schema at that point. |
+-----------------------------------------------------------------------+
-----------------------------------------------------------------------
**15. Phase Build Plan**
-----------------------------------------------------------------------
--------- ---------------------------------------------------------------
**PHASE **Full Working Application**
1**
--------- ---------------------------------------------------------------
Everything a user needs to manage their professional and personal life
daily. Deployed to DEV, tested, then promoted to PROD with migrated
data.
-----------------------------------------------------------------------
**Step 1 - Foundation (1-2 days)**
-----------------------------------------------------------------------
1. Apply R1 PostgreSQL schema to lifeos_dev
2. Run data migration script: R0 -\> R1 field mapping
3. Verify migrated data: 3 domains, 10 areas, 18 projects, 73 tasks
4. Stand up Docker stack: lifeos-db, lifeos-prod, lifeos-dev
5. Configure Nginx for both domains
6. Obtain SSL certificates via Certbot
7. Verify HTTPS access to both domains
8. Build: core/database.py, core/base_repository.py,
core/generic_router.py
9. Build: config/ YAML files (entities.yaml, menu.yaml)
10. Build: base.html shell with sidebar, topbar, theme classes
11. Build: \_list.html, \_form.html, \_empty.html generic templates
-----------------------------------------------------------------------
**Step 2 - Config-Driven Entities (1 day)**
-----------------------------------------------------------------------
12. Wire all 12 config-driven entities through generic_router
13. Domains, areas, context_types, weblinks, weblink_folders,
note_folders, time_budgets, task_templates, task_template_items,
milestones, release_domains, release_projects
14. Verify CRUD for all 12 entities
-----------------------------------------------------------------------
**Step 3 - Core Task and Project Management (3-4 days)**
-----------------------------------------------------------------------
15. Tasks: full CRUD, subtasks, priority, status, context, tags,
estimates, energy, waiting_for
16. Projects: CRUD, progress calculation, status management
17. Daily focus: date-scoped list, drag reorder, timer per task
18. Dependencies: DAG implementation, cycle detection, status cascade
19. Task templates: instantiation with subtask generation
20. Bulk actions: mark done, move, delete, add to focus
21. Overdue visual treatment, relative date language system
-----------------------------------------------------------------------
**Step 4 - Knowledge and Content (2-3 days)**
-----------------------------------------------------------------------
22. Notes: rich text editor, folders, M2M projects, wiki-linking \[\[
23. Decisions: CRUD, project/contact links, supersession chain
24. Files: upload, download, inline preview (images + PDFs)
25. Lists and list items: CRUD, checklist completion
26. Links and weblinks: CRUD, folder organization
-----------------------------------------------------------------------
**Step 5 - Meetings, Contacts, CRM (2 days)**
-----------------------------------------------------------------------
27. Meetings: agenda, transcript, notes, action items -\> tasks
28. Contacts: CRUD, associations with roles
29. Appointments: CRUD, calendar integration
30. Follow-up reminders: per-contact, dashboard surfacing
31. Meeting series via parent_id
-----------------------------------------------------------------------
**Step 6 - Processes and Releases (2 days)**
-----------------------------------------------------------------------
32. Processes: workflow vs checklist type, step management
33. Process runs: template snapshot, task generation, step completion
34. Releases: system-level CRUD, M2M project associations
35. Release detail: aggregate progress across projects, milestone
display
36. Task release_id assignment, backlog view
-----------------------------------------------------------------------
**Step 7 - Time Management (2 days)**
-----------------------------------------------------------------------
37. Time tracking: start/stop timer, topbar pill, time_entries
38. Time blocks: create on calendar view, context/energy fields
39. Time budgets: domain weekly targets, overcommitment surfacing
40. Eisenhower matrix view
41. Dashboard: today estimate vs available, weekly metrics widget
-----------------------------------------------------------------------
**Step 8 - Search and Capture (1-2 days)**
-----------------------------------------------------------------------
42. Global search: tsvector setup on all tables, Cmd/K modal
43. Scoped search within project views
44. Capture: multi-line paste parse, context pre-fill, convert to any
type
45. Capture bulk undo via import_batch_id
-----------------------------------------------------------------------
**Step 9 - UX Polish and Admin (1-2 days)**
-----------------------------------------------------------------------
46. Admin Trash: all soft-deleted entities, restore, permanent delete
47. Admin context types manager
48. Empty states on all list views
49. Skeleton loading screens
50. Toast notification system
51. Confirmation dialogs for destructive actions
52. CSV export: tasks, projects, contacts, decisions
53. Dashboard: focus list, deadlines, calendar, metrics, reminders
widgets
54. Calendar view: appointments + meetings + task due dates
-----------------------------------------------------------------------
**Step 10 - Promotion to Production**
-----------------------------------------------------------------------
55. Apply schema to lifeos_prod
56. Run data migration on lifeos_prod
57. Smoke test all views on production data
58. Configure automated daily backup cron job
59. Document final deployed state
--------- ---------------------------------------------------------------
**PHASE **DAG Visualization and MCP/AI Gateway**
2**
--------- ---------------------------------------------------------------
- DAG node graph visualization on project view (tasks as nodes,
dependencies as edges)
- Critical path calculation and highlighting
- MCP server container: Python MCP server with shared tool core
- OpenAI-compatible /tools/openai endpoint on same container
- Model registry YAML configurable from Admin UI
- API key authentication for MCP
- Nginx routing for /ai/ path
- Claude Desktop connection config
- Note version history (note_version_history table)
- Pipeline / deal stages for CRM contacts
- Browser extension design and scoping
--------- ---------------------------------------------------------------
**PHASE **Polish and Advanced Features**
3**
--------- ---------------------------------------------------------------
- AI-assisted import: unstructured paste -\> LLM -\> structured
preview -\> confirm
- Dark/light theme switcher in UI (data-theme toggle, localStorage,
Phase 1 has CSS ready)
- Mobile swipe actions on task rows: complete, delete, add to focus
- Export: JSON (full data dump), PDF (reports), Markdown (notes)
- Full keyboard navigation: tab order, arrow keys, shortcuts (N, D, F,
Enter)
- Browser extension for weblink capture
- Habit tracking subsystem
- Goals/OKRs hierarchy above domains
- External calendar sync (Google Calendar / Outlook) - OAuth, webhooks
- Pre/post meeting AI summaries (requires Phase 2 MCP)
- Basic application authentication (session-based login)
-----------------------------------------------------------------------
**16. Migration Plan (R0 to R1)**
-----------------------------------------------------------------------
**16.1 Current State**
---------------- ------------------------------------------------------
**R0 data lifeos_prod on defiant-01 PostgreSQL container
location**
**Migrated 3 domains, 10 areas, 18 projects, 73 tasks, 2 notes, 5
records** links, 5 daily_focus, 80 capture, 6 context_types
**Files** Empty (Supabase Storage URLs obsolete - file uploads
start fresh in R1)
**R0 Supabase client, Render hosting - decommissioned after
application** R1 promotion
---------------- ------------------------------------------------------
**16.2 Key Transformations Required**
- notes.content_format: update all R0 \'markdown\' values to \'rich\'
- All tables: add is_deleted=false, deleted_at=null, sort_order
sequential by created_at
- tasks: add release_id=null, estimated_minutes=null,
energy_required=null, waiting_for_contact_id=null
- notes: add folder_id=null, is_meeting_note=false, meeting_id=null,
title NOT NULL (fill empty titles with \'Untitled Note\')
- capture: add converted_to_type=null, converted_to_id=null,
import_batch_id=null
- context_types: add sort_order, is_deleted=false
**16.3 Migration Script Approach**
> \# migration/r0_to_r1.py
>
> \# 1. Connect to lifeos_prod (already populated with R0 data)
>
> \# 2. ALTER TABLE statements add new R1 columns
>
> \# 3. UPDATE statements set default values for new columns
>
> \# 4. Create all new R1 tables (empty)
>
> \# 5. Create indexes and tsvector triggers
>
> \# 6. Populate context_types with system defaults
>
> \# 7. Create built-in Weekly Review process template
>
> \# 8. Verify row counts match expected
Migration runs against lifeos_dev first. Once verified, same script
applies to lifeos_prod. Total migration time expected under 5 minutes
for current data volume.
-----------------------------------------------------------------------
**17. Appendix: Complete Table Inventory**
-----------------------------------------------------------------------
---------------------- -------------- ---------------------------------------
**Table** **Category** **Key FKs / Notes**
domains Core hierarchy No parent
areas Core hierarchy domain_id
projects Core hierarchy domain_id, area_id (opt)
tasks Core hierarchy domain_id, area_id, project_id,
release_id, parent_id,
waiting_for_contact_id (all opt)
notes Core hierarchy domain_id, project_id, folder_id,
meeting_id (all opt)
note_folders Core hierarchy parent_id self-ref
lists Core hierarchy domain_id, area_id, project_id (all
opt)
list_items Core hierarchy list_id, parent_item_id self-ref
links Core hierarchy domain_id, project_id
files Core hierarchy Associations via file_mappings junction
contacts System level No parent
appointments System level Associations via contact_appointments
meetings System level parent_id self-ref for series
decisions System level meeting_id (opt), superseded_by_id
self-ref
releases System level M2M via release_projects,
release_domains
milestones System level release_id (opt), project_id (opt)
processes System level process_type: workflow\|checklist
process_steps System level process_id
process_runs System level process_id, project_id (opt),
contact_id (opt)
process_run_steps System level run_id - content immutable after run
start
daily_focus System level task_id, focus_date
capture System level Polymorphic converted_to_type/id
task_templates System level Instantiated to create tasks+subtasks
task_template_items System level template_id
time_entries Time mgmt task_id - start/stop timer records
time_blocks Time mgmt task_id (opt) - calendar slots
time_budgets Time mgmt domain_id - weekly hours target
weblink_folders System level parent_id self-ref
weblinks System level M2M via folder_weblinks
context_types Lookup SERIAL pk, is_system flag
reminders System level Polymorphic entity_type/entity_id
dependencies Universal Polymorphic blocker+dependent, 4 types
junction
note_projects Junction note_id, project_id, is_primary
note_links Junction source_note_id, target_note_id - wiki
graph
file_mappings Junction file_id, context_type, context_id
release_projects Junction release_id, project_id
release_domains Junction release_id, domain_id
contact_tasks Junction contact_id, task_id, role
contact_projects Junction contact_id, project_id, role
contact_lists Junction contact_id, list_id, role
contact_list_items Junction contact_id, list_item_id, role
contact_appointments Junction contact_id, appointment_id, role
contact_meetings Junction contact_id, meeting_id, role
decision_projects Junction decision_id, project_id
decision_contacts Junction decision_id, contact_id, role
meeting_tasks Junction meeting_id, task_id, source
process_run_tasks Junction run_step_id, task_id
folder_weblinks Junction folder_id, weblink_id
note_version_history Phase 2 note_id, body snapshot, version_num
pipelines Phase 2 CRM deal stage tracking
---------------------- -------------- ---------------------------------------
*Life OS Architecture Design Document \| Version 2.0 \| February 2026 \|
Approved for Build*
Reference in New Issue View Git Blame Copy Permalink