forked from eva/focus-flow
99 lines
4.6 KiB
Markdown
99 lines
4.6 KiB
Markdown
# Starter Architecture Notes
|
|
|
|
## Initial architecture decision
|
|
|
|
Start as a pure Dart scheduling-core package. Do not begin with UI. The scheduling rules are the hardest and most important part of the product, and they should be testable without a Flutter app running.
|
|
|
|
## Future shape
|
|
|
|
```text
|
|
Flutter UI
|
|
↓
|
|
View/application state
|
|
↓
|
|
Pure Dart scheduling core
|
|
↓
|
|
Repository interfaces
|
|
↓
|
|
MongoDB persistence adapter (planned later)
|
|
↓
|
|
Future sync layer, if explicitly planned
|
|
```
|
|
|
|
## Why pure Dart first
|
|
|
|
- Easier to test scheduling rules.
|
|
- Less UI noise for Codex.
|
|
- Cleaner migration into Flutter later.
|
|
- Avoids premature sync/background complexity.
|
|
|
|
## Key invariant
|
|
|
|
The scheduling core must never move locked or inflexible blocks during automatic rescheduling.
|
|
|
|
Flexible end-of-day rollover should use an explicit source-day window when
|
|
available. That prevents planned flexible tasks from future days from being
|
|
pulled into tomorrow during recovery.
|
|
|
|
Backlog staleness in the current V1 domain model uses task creation age for both
|
|
the stale filter and green/blue/purple marker. A later MongoDB-backed
|
|
persistence pass may add a separate backlog-entered timestamp, but the current
|
|
core keeps the timestamp semantics consistent and database-independent.
|
|
|
|
Surprise task logging is a domain action, not UI behavior. A logged surprise task
|
|
is completed immediately. If it has a time interval, overlapping flexible tasks
|
|
are pushed by the normal scheduler, required visible overlaps are reported, and
|
|
locked overlaps are tracked as hidden data rather than rendered as normal tasks.
|
|
|
|
Child tasks are direct parent-owned tasks, not dependency graph nodes. Completing
|
|
all direct children can complete the parent, and explicitly completing a parent
|
|
can force-complete its direct children. Scheduling still treats child ownership
|
|
as metadata and does not block placement based on parent/child state.
|
|
|
|
V1 treats task lifecycle status and movement history as separate concepts.
|
|
Durable task statuses are planned, active, completed, missed, cancelled, no
|
|
longer relevant, and backlog. Pushes, restores from backlog, and burnout skips
|
|
are activity/stat metadata rather than durable statuses. This preserves the
|
|
product language from the design spec while keeping scheduling state
|
|
deterministic and testable. The detailed backend decision is recorded in
|
|
`Codex Documentation/Current Software Plan/V1_ADR_001_Lifecycle_Metadata_Reminder_Semantics.md`.
|
|
|
|
`updatedAt` means last domain-level modification only. It should not be used as
|
|
a proxy for completion time, actual work time, missed time, or backlog-entry
|
|
time. Blocks 12, 13, and 15 add those fields explicitly where the product needs
|
|
them.
|
|
|
|
Recurring locked time uses civil dates and wall-clock times, not implicit local
|
|
`DateTime` values. The scheduling core converts a civil date plus wall time into
|
|
an instant only through an explicit time-zone resolver supplied by the
|
|
application boundary. Daylight-saving behavior is deterministic: nonexistent
|
|
local times shift forward by default, repeated local times choose the earlier
|
|
instant by default, and callers may request rejection or the later repeated
|
|
instant. Overnight locked rules are rejected instead of silently split or
|
|
normalized.
|
|
|
|
Persistence should keep these concepts separate. Instants are stored as UTC
|
|
ISO-8601 strings, civil dates as `YYYY-MM-DD`, and wall times as `HH:MM`; date
|
|
and wall-time fields must not be converted through UTC in a way that can shift
|
|
the user's intended local day.
|
|
|
|
## Persistence direction
|
|
|
|
MongoDB is the committed persistence target. The V1 scheduling core should still
|
|
remain persistence-independent and testable without a running database. Repository
|
|
interfaces should be designed so a later MongoDB adapter can persist document-shaped
|
|
models without importing MongoDB APIs into scheduling logic.
|
|
|
|
Current V1 persistence preparation includes pure Dart repository interfaces,
|
|
in-memory fakes for tests, UTC DateTime conventions, civil-date and wall-time
|
|
string conventions, stable enum names, and MongoDB-friendly document-shaped map
|
|
helpers. It does not include a MongoDB driver, adapter implementation,
|
|
connection string, Atlas/cloud setup, local MongoDB server requirement, user
|
|
accounts, network sync, background sync, or mobile background reconciliation.
|
|
|
|
Sync remains future work and should only be added if an active plan explicitly
|
|
asks for it. The core should continue to operate in-memory for tests and local
|
|
domain behavior until a later MongoDB adapter plan is approved.
|
|
|
|
Do not add alternative database assumptions to this project unless
|
|
the product owner explicitly changes the persistence decision.
|