{"id":47744306,"url":"https://github.com/kazandthecompiler/dopaflow","last_synced_at":"2026-04-16T02:01:00.416Z","repository":{"id":348777532,"uuid":"1199514714","full_name":"KazAndTheCompiler/DopaFlow","owner":"KazAndTheCompiler","description":"Tasks, habits, focus, journal, calendar, and spaced repetition — unified. Built for ADHD brains. Offline-first. No cloud, no subscription.","archived":false,"fork":false,"pushed_at":"2026-04-10T05:13:01.000Z","size":47995,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T07:17:43.828Z","etag":null,"topics":["adhd","electron","fastapi","habit-tracker","journal","neurodivergent","pomodoro","productivity","pwa","react","spaced-repetition","sqlite","task-manager","typescript"],"latest_commit_sha":null,"homepage":"https://portfolio-roan-zeta-ag6e5ttlvw.vercel.app/dopaflow/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KazAndTheCompiler.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap_obsidian_strategy.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-02T12:30:43.000Z","updated_at":"2026-04-10T05:12:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KazAndTheCompiler/DopaFlow","commit_stats":null,"previous_names":["kazandthecompiler/dopaflow"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/KazAndTheCompiler/DopaFlow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KazAndTheCompiler%2FDopaFlow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KazAndTheCompiler%2FDopaFlow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KazAndTheCompiler%2FDopaFlow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KazAndTheCompiler%2FDopaFlow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KazAndTheCompiler","download_url":"https://codeload.github.com/KazAndTheCompiler/DopaFlow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KazAndTheCompiler%2FDopaFlow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31867712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adhd","electron","fastapi","habit-tracker","journal","neurodivergent","pomodoro","productivity","pwa","react","spaced-repetition","sqlite","task-manager","typescript"],"created_at":"2026-04-03T00:26:56.541Z","updated_at":"2026-04-16T02:01:00.411Z","avatar_url":"https://github.com/KazAndTheCompiler.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DopaFlow\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![React](https://img.shields.io/badge/React_18-20232A?style=flat-square\u0026logo=react\u0026logoColor=61DAFB)](https://react.dev/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=flat-square\u0026logo=fastapi\u0026logoColor=white)](https://fastapi.tiangolo.com/)\n[![Electron](https://img.shields.io/badge/Electron-47848F?style=flat-square\u0026logo=electron\u0026logoColor=white)](https://www.electronjs.org/)\n[![SQLite](https://img.shields.io/badge/SQLite-003B57?style=flat-square\u0026logo=sqlite\u0026logoColor=white)](https://sqlite.org/)\n[![Offline First](https://img.shields.io/badge/Offline--first-no_cloud_required-6B7280?style=flat-square)](#offline-first)\n[![Get on Gumroad](https://img.shields.io/badge/Stable_build-$1_on_Gumroad-FF90E8?style=flat-square\u0026logo=gumroad\u0026logoColor=white)](https://kirkhenrik.gumroad.com/l/woosbf)\n[![License: PolyForm NC](https://img.shields.io/badge/License-PolyForm_NC_1.0-blue?style=flat-square)](LICENSE)\n\n**A productivity app for ADHD brains — tasks, habits, focus, journaling, calendar, alarms, and spaced repetition in one offline-first surface.**\n\n---\n\n## What it does\n\nDopaFlow brings tasks, habits, focus, journaling, calendar, alarms, and spaced repetition into one place without the mental overhead of bouncing between five different apps.\n\n| Surface | What it covers |\n|---|---|\n| **Tasks** | Full CRUD, subtasks, priorities, time logging, Kanban \u0026 Eisenhower boards, bulk operations, natural language quick-add |\n| **Habits** | Daily check-ins, streaks, freeze/unfreeze, correlation insights, progress rings, heatmap |\n| **Focus** | Pomodoro sessions, task picker, custom duration, session history and stats |\n| **Journal** | Markdown editor, voice dictation, wikilinks, version history, auto-export to `.md`, templates |\n| **Calendar** | Events with drag-to-reschedule and resize in Day view, click-to-edit modal, recurring blocks, Google sync, peer calendar sharing |\n| **Alarms** | Schedule alarms, TTS or YouTube audio queue, background service worker |\n| **Review** | Spaced repetition (SM-2), Anki import, deck management, keyboard shortcuts, inline card editor |\n| **Packy** | Contextual memory system to help resurface things you forgot |\n| **Digest** | End of day summary, momentum score, weekly insights in plain language |\n| **Gamification** | XP, badges, levels — because dopamine helps |\n\n---\n\n## Tech stack\n\n- **Frontend:** React 18 + TypeScript + Vite + PWA\n- **Backend:** FastAPI + SQLite or Turso\n- **Desktop:** Electron\n- **Themes:** 24 built-in skins (19 in the picker, 5 gradient variants)\n\n---\n\n## Repo structure\n\n```\ndopaflow/\n├── backend/          FastAPI app (domains, routers, services, repositories)\n├── desktop/          Electron shell for packaged desktop builds\n├── frontend/         React + TypeScript SPA (surfaces, components, hooks, api)\n├── shared/           Shared TypeScript types and version\n├── skinmaker/        Standalone skin editor utility\n├── docs/             Architecture docs, changelog, user guide\n├── scripts/          Release and CI helper scripts\n├── tools/            Dev tooling (MCP servers, etc.)\n├── release/          Packaging output and staging\n└── internal/         Personal artifacts and archived content (not product-facing)\n```\n\nFor a full architecture breakdown, see [`docs/architecture-overview.md`](docs/architecture-overview.md).\n\n---\n\n## Status\n\n**Best for:**\n- Local self-hosting (Docker, single server)\n- Single-user offline-first workflows\n- Developers and contributors\n\n**Not designed for:**\n- Multi-user hosted SaaS\n- Horizontal scaling across multiple servers (SQLite is single-writer)\n- Zero-config enterprise deployment\n\n**For production exposure beyond localhost:** set `DOPAFLOW_ENFORCE_AUTH=true` in your `.env` and configure a strong `DOPAFLOW_API_KEY`.\n\n---\n\n## Quick start\n\n**Use this if:** you want to run DopaFlow locally and see if it fits your workflow.\n\n### Option A — Docker (fastest, no setup)\n\n```bash\ncp .env.example .env\ndocker compose up --build\n# open http://localhost:3000\n```\n\nEverything in one command. No Python, no Node, no manual config. The Docker path is the recommended first try.\n\n### Option B — Local development\n\nTwo terminals:\n\n```bash\n# Terminal 1: backend\ncd backend\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\ncp ../.env.example ../.env\nuvicorn app.main:app --reload\n\n# Terminal 2: frontend\ncd frontend\nnpm install\nnpm run dev\n# open http://localhost:5173\n```\n\nFrontend (`5173`) proxies `/api/*` to backend (`8000`).\n\n### Option C — Desktop package\n\n```bash\ncd desktop\nnpm ci \u0026\u0026 npm test\nnpm run dist:stable:linux\n```\n\nRequires Python 3.11 or 3.12 and Node 18+.\n\n### Requirements\n\n- Node 18+\n- Python 3.11 or 3.12 (run `make doctor` to verify)\n\n---\n\n## Development\n\n### Repository commands\n\n```bash\nmake help              # show all available commands\nmake dev               # start frontend dev server\nmake backend           # start backend dev server\nmake test             # run all tests (backend + frontend typecheck)\nmake test-backend      # run backend tests with pytest\nmake test-frontend    # run frontend typecheck\nmake test-e2e         # run frontend E2E smoke tests\nmake lint             # lint all projects (backend + frontend)\nmake lint-backend     # lint backend with ruff\nmake lint-frontend    # lint frontend with ESLint\nmake format           # format code (prettier + ruff)\nmake format-check     # check formatting without modifying\nmake validate         # run all quality checks (lint + typecheck + backend tests)\nmake typecheck        # TypeScript typecheck frontend\nmake build            # build frontend production bundle\nmake doctor           # check environment readiness\n```\n\n### Frontend surfaces\n\nReact-router surfaces under `frontend/src/surfaces/`: Today, Tasks, Calendar, Focus, Journal, Settings, Search, Commands.\n\nShared components, hooks, and API clients live under `frontend/src/`.\n\n### Backend domains\n\nFastAPI routers under `backend/app/domains/`. Each domain follows `router/service/repository/schemas` layering.\n\n### Browser E2E tests\n\n```bash\ncd frontend\nnpm run test:e2e:smoke    # startup + navigation regression (mocked, fast)\nnpm run test:e2e:core     # broader mocked coverage\nnpm run test:e2e:release  # full release slice used in CI\n```\n\n### Backend tests\n\n```bash\ncd backend\npytest tests/ -v\n```\n\nSee [`docs/backend-architecture.md`](docs/backend-architecture.md) for backend layout details.\n\n---\n\n## Release builds\n\nDesktop packaging is wired through [`.github/workflows/release.yml`](.github/workflows/release.yml).\n\nRecommended path:\n\n- push to `main` for normal CI confidence\n- push a `v*` tag to build release artifacts and publish a GitHub Release\n- Linux `AppImage` artifact is the primary desktop package\n\nRelease gates include repo hygiene checks, frontend E2E coverage, desktop runtime tests, and AppImage payload verification.\n\nFor the full release checklist, see [`docs/release-checklist.md`](docs/release-checklist.md).\n\n---\n\n## Two versions\n\n| | Dev (this repo) | Stable |\n|---|---|---|\n| **Cost** | Free | $1 |\n| **Updates** | Pull manually from GitHub | Auto-updates when pushed |\n| **Status** | Active development | Tested, tagged releases |\n| **Support** | None | None, but issues are welcome |\n\n👉 **[Get the stable build on Gumroad](https://kirkhenrik.gumroad.com/l/woosbf)** — $1, pay what you want above that.\n\n---\n\n## Offline first\n\nYour data lives on your device. No account required. No cloud dependency. No subscription.\n\nOptional Google Calendar sync uses OAuth. Your credentials are not baked into the app.\n\n---\n\n## Voice commands\n\nVoice commands use the same preview → confirm → execute path as typed commands, without rigid prefixes.\n\nExamples:\n- `buy milk tomorrow`\n- `journal today felt clearer after walking`\n- `schedule dentist tomorrow at 2pm for 45 minutes`\n- `start focus for 25 minutes`\n\n---\n\n## Known gaps (v2 beta)\n\n- Skeleton loaders are in place on core loading-heavy surfaces; the rest still needs a consistency pass\n- Obsidian bridge is manual-first: no live watch, no merge UI, no vault-wide import outside the configured task folder\n- Digest delivery, scheduling, and richer coaching-style guidance are still missing\n- Mobile swipe-to-complete on task rows is not implemented\n- Calendar drag support is Day-view-only; Week and Month views are click-to-open\n- Nutrition food library editing and search is basic\n- Review APKG test coverage is improving but not yet comprehensive\n\n---\n\n## Obsidian bridge\n\nDopaFlow has a local-first Obsidian vault bridge.\n\nWhat it supports today:\n\n- vault path/configuration in Settings\n- journal push/pull using Markdown daily notes\n- task collection push/pull using Obsidian-compatible checkbox syntax\n- daily task section push into existing daily notes using bounded markers\n- task import preview/import from vault task files\n- rollback, conflict tracking, and conflict preview for indexed vault files\n\nCurrent shape:\n- journal notes: `Daily/YYYY-MM-DD.md`\n- tasks: `Tasks/Inbox.md` + one `Tasks/\u003cproject\u003e.md` per project\n- DopaFlow task identity stored in hidden HTML comments (`\u003c!--df:tsk_123--\u003e`)\n- daily-note task injection only touches the managed `dopaflow:tasks` section\n\nWhat it does not do yet: live filesystem watch, cloud sync, merge UI, vault-wide import outside the configured task folder.\n\nSee [`docs/obsidian_bridge.md`](docs/obsidian_bridge.md) for workflow and compatibility rules.\n\n---\n\n## Why these features exist\n\nADHD is dopamine hunting. You build systems around that or you drown in the lack of them.\n\n- **Smart Memory** — stores by association, not exact words. Coffee → hot drink, morning ritual, warm beverage. Built for the ADHD reality: decent long-term memory, terrible short-term memory.\n- **Spaced repetition** — Anki-style SM-2 forces proper encoding. For neurodivergent people, far more useful than most schools admit.\n- **Alarms with TTS** — a spoken reminder lands differently than a silent badge.\n- **Tasks that roll over** — guilt-free. If you planned four hours and it took six, the task moves. That is information, not failure.\n- **Calorie and habit correlation** — people often do not see their own patterns until the data is in front of them.\n\n---\n\n## Who this is for\n\nPrimarily people with ADHD. But also anyone with a stressful life, a bad routine, a messy brain, or a history with productivity apps that assume too much about your baseline.\n\nThis is not about masking better. It is about ownership. Accountability without guilt.\n\n---\n\n## Credits\n\nBuilt by **Henry (KazAndTheCompiler)** — ex-navigator, AuDHD, Jutland, Denmark.\n\nCo-authored with **[Claude](https://claude.ai)** (Anthropic) and **[MiniMax](https://www.minimax.io/)** M2.7 (MiniMax) — pair-programmed across the full stack.\n\n---\n\n## License\n\n**Personal use only.** You may run, modify, and learn from this code for personal non-commercial use. Redistribution, resale, or commercial use without permission is not allowed.\n\nFor anything else, open an issue and ask.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkazandthecompiler%2Fdopaflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkazandthecompiler%2Fdopaflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkazandthecompiler%2Fdopaflow/lists"}