vexolmer/life_dash

Purpose and entry points

Local FastAPI application that treats an Obsidian vault’s Markdown/YAML notes as the source of truth, synchronizes them into SQLite, and renders analytics/records server-side. Web startup is src/main.py; command-line access is cli.py. Persistent local state is data/db.sqlite.

Application composition

The application is split into content modules with the same layered shape: SQLModel schema, repository, service, transformer, and FastAPI router.

• Books: src/modules/books/models.py, src/modules/books/service.py, src/modules/books/router.py

• Games: src/modules/games/models.py, src/modules/games/service.py, src/modules/games/router.py

• Daily notes, including daily records and time-log relationships: src/modules/daily/models.py, src/modules/daily/service.py, src/modules/daily/router.py

This boundary isolates module-specific note formats, validation, persistence, and analytics.

Synchronization / ETL boundary

Parsing is a one-way import from Obsidian files to the local database; the web UI does not edit source content. src/parser/engine.py scans vault directories and file modification metadata. src/parser/sync.py orchestrates module syncs, decides whether records require update, invokes module transformers, skips invalid inputs, and returns synchronization statistics for the UI.

Module transformers convert frontmatter and Markdown bodies into SQLModel-ready records:

src/modules/books/transformer.py, src/modules/games/transformer.py, and src/modules/daily/transformer.py. The Daily transformer is materially distinct because it regex-parses structured sleep, health, and time-tracking sections and produces parent/child daily-log data.

Persistence and migration model

SQLite is accessed through SQLModel/SQLAlchemy infrastructure in src/core/database.py. Repositories encapsulate queries and upserts rather than exposing database operations to routers:

src/modules/books/repository.py, src/modules/games/repository.py, src/modules/daily/repository.py.

Schema evolution is managed by Alembic under migrations/env.py and migrations/versions/. Daily persistence has the important ownership boundary: a DailyNote and its time logs are synchronized together, supporting replacement/cascade behavior.

Request, analytics, and rendering flow

FastAPI routers call services, which obtain records through repositories and compute presentation-ready metrics such as filters, aggregates, reading/game progress, ISO-week calculations, and daily averages. Routes render Jinja templates rather than serving a separate frontend API. The shared landing/dashboard route is src/web/router.py; module pages are rooted in their module routers.

Templates establish the presentation boundary:

src/web/templates/layout.html,

src/web/templates/pages/books/,

src/web/templates/pages/daily/, and

src/web/templates/pages/games/.

HTMX enables partial interactions such as sync reporting via src/web/templates/components/sync_report.html.

Core runtime infrastructure

Configuration, including vault/database paths, is centralized in src/core/config.py; logging is configured in src/core/logger.py; dashboard/statistical caching is in src/core/cache.py. Operational failures during parsing are intended to be logged while malformed files are excluded from persistence. Shared base CRUD behavior resides in src/common/base.py.

External technologies and boundaries

Runtime dependencies are FastAPI, SQLModel with local SQLite, Pydantic Settings, python-frontmatter, and Loguru. The UI is server-rendered Jinja2 with HTMX and static styling in src/web/static/css/style.css; browser-side charts use Chart.js. Obsidian vault files are the upstream external data source; no separate database server or write-back integration is implied. scripts/mass_update_daily_notes.py is an offline vault-maintenance utility, outside the application request path.