Skip to content

README.md

Latest commit

 

History

History
114 lines (88 loc) · 2.7 KB

README.md

File metadata and controls

114 lines (88 loc) · 2.7 KB

Productivity App V1

An English-first productivity system built around PARA + Weekly Review.

Features

  • Inbox capture and clarify flow (task, project, resource)
  • PARA entity management (areas, projects, resources, archive)
  • Task planning with priority, status, due date, and timeboxing
  • Weekly review summaries and dashboard KPI cards
  • Habit tracking with daily check-ins, current streak, longest streak, and weekly completion rate
  • Demo seed and clean reset flows

Stack

  • Backend: FastAPI + Pydantic + sqlite3
  • Frontend: Server-rendered HTML + Vanilla JS + Chart.js
  • Database: SQLite (data/app.db)
  • Environment and package management: uv
  • Test: pytest + FastAPI TestClient

Setup

uv python install 3.11
uv sync --dev

Run

uv run uvicorn app.main:app --reload

App URL: http://127.0.0.1:8000

Tests

uv run pytest -q

Runtime Notes

  • The project runs on Python 3.11. The .python-version file pins the expected runtime.
  • Destructive system endpoints are disabled by default.
  • If you need demo data or a full reset, start the app with:
PRODUCTIVITY_ENABLE_SYSTEM_MUTATIONS=1 uv run uvicorn app.main:app --reload

API Summary

  • Inbox
    • POST /api/v1/inbox/items
    • GET /api/v1/inbox/items
    • PATCH /api/v1/inbox/items/{inbox_item_id}/clarify
  • PARA
    • GET /api/v1/areas
    • POST /api/v1/areas
    • GET /api/v1/projects
    • POST /api/v1/projects
    • PATCH /api/v1/projects/{project_id}
    • POST /api/v1/resources
    • POST /api/v1/archive/items/{item_id}
  • Tasks
    • GET /api/v1/tasks
    • POST /api/v1/tasks
    • PATCH /api/v1/tasks/{task_id}
    • POST /api/v1/tasks/{task_id}/timebox
  • Habits
    • GET /api/v1/habits
    • POST /api/v1/habits
    • POST /api/v1/habits/{habit_id}/checkins
    • GET /api/v1/habits/summary
  • Review / Dashboard
    • GET /api/v1/review/weekly?week=YYYY-WW
    • GET /api/v1/dashboard/overview
  • System
    • POST /api/v1/system/seed
    • POST /api/v1/system/reset

Seed and Reset

  • The app must be started with PRODUCTIVITY_ENABLE_SYSTEM_MUTATIONS=1 before using the endpoints below.
  • To load demo data:
curl -X POST http://127.0.0.1:8000/api/v1/system/seed \
  -H "Content-Type: application/json" \
  -d '{"mode":"demo"}'
  • To start from an empty state:
curl -X POST http://127.0.0.1:8000/api/v1/system/seed \
  -H "Content-Type: application/json" \
  -d '{"mode":"empty"}'
  • To reset all data:
curl -X POST http://127.0.0.1:8000/api/v1/system/reset

Roadmap (V2)

  • Google Drive synchronization
  • AI-assisted weekly summaries and prioritization suggestions
  • Calendar integrations
  • Multi-user authentication