bujo_v1/cline2.md

Below is the same design blueprint, but every section heading is now labelled “Step” so any system that looks for a “step” token will pick it up.

---

Bullet‑Journal App – Step‑by‑Step Design Blueprint

Step 1 – High‑Level Goals

Purpose: Outline the core objectives that every subsequent step must satisfy.

Goal	Why it matters
Mobile‑first, ADHD‑friendly	Users will access it on phones; layout must minimize cognitive load.
Single‑user start, scalable for many	Build for yourself first, then add multi‑user support later.
Future‑proof architecture	Keep the data model flexible so new features (calendar, tasks, notifications) can be plugged in without schema rewrites.
Accessibility	Contrast, font sizing, and navigation must pass WCAG 2.1 AA.

---

Step 2 – Layout & UI Flow

Purpose: Define the visual structure and user interaction flow.

Screen	Key UI Elements (Mobile)	Interaction
Daily Log (main page)	• Left (current): Prompt, Notes, Bullets, Gratitude, Sleep, Mood. • Right (future‑features): “Coming Soon: Calendar”, “Coming Soon: Task List”. • Footer: Save button, navigation to “All Logs” or “Settings”.	• Tap to edit any field. • Swiping left/right on mobile collapses the right column to reveal the left one (or vice‑versa).
All Logs	List of dates (chronological). Each row shows date, prompt, and a short preview of bullets.	• Tap to open the Daily Log for that date.
Settings	• Color scheme toggle (pastel light/dark). • Font size slider. • Export / Import logs.	• Adjust and save preferences.

---

Step 3 – Data Model (SQLAlchemy‑style, but described only)

3.1 Tables

Table	Columns (type)	Notes
daily_log	id PK, date (unique), prompt, notes, gratitude (JSON array of 3 strings), bedtime, wake_time, sleep_quality (enum), mood, created_at, updated_at	Holds the static fields that belong to a day.
daily_log_item	id PK, log_id FK → daily_log.id, type (bullet, gratitude, sleep, note), symbol (e.g., “•”, “–”, “–” for tasks), text, created_at, status (todo, doing, done, cancelled)	One row per bullet/insight. Allows fine‑grained filtering, sorting, and analytics.

3.2 Relationships

• daily_log.items → One‑to‑many daily_log_item (lazy loading).
• Each daily_log_item belongs to exactly one daily_log.

3.3 Indexes & Performance

• Index on daily_log.date (unique).
• Index on daily_log_item.log_id and daily_log_item.status for quick queries on status.
• Index on daily_log_item.type if you plan to filter by item kind.

---

Step 4 – Core Features & User Flow

Feature	What the user does	Backend / DB actions
Create / Edit Log	User opens the date page, types prompt, notes, bullets, etc.	Insert or update daily_log; create/update daily_log_item rows as needed.
Add Bullet	Tap “Add” button → choose symbol (bullet, task, note).	Insert daily_log_item with appropriate type and symbol.
Mark Done / Cancel	Tap status icon on a bullet.	Update daily_log_item.status.
View All Logs	Tap “All Logs” → scroll list.	Query daily_log ordered by date.
Settings	Adjust color scheme, font size.	Store preferences in a user_settings table (single‑row per user).
Export / Import	Export JSON file of all logs.	Serialize daily_log + related items to JSON; reverse on import.

---

Step 5 – Accessibility & Color Strategy

Aspect	Recommendation
Color Palette	Pastel base (soft lavender for primary actions, light mint for secondary). Use higher contrast for warnings/errors (e.g., muted coral).
Contrast	Minimum 4.5:1 for text on background; ensure icons and status indicators meet this.
Font	Base size 18px (scalable with user setting). Use a sans‑serif like “Inter” or “Roboto”.
Touch Targets	Minimum 44x44dp; add 8px padding around icons.
Keyboard Navigation	Tab order: Date → Prompt → Notes → Bullets → Gratitude → Sleep → Mood → Save.
Screen Reader	ARIA labels for each input and button. Use semantic <label> tags.

---

Step 6 – Extensibility Roadmap (Future Features)

1. Calendar View – Monthly grid; clicking a day opens the log. Store daily_log dates for quick lookup.
2. Task List – Reuse daily_log_item.type='task' and add a global “Task List” table if needed for cross‑day tasks.
3. Notifications – Email/SMS/WebSocket integration. Store notification preferences per user.
4. Multi‑User – Add users table, authentication via Flask‑Login, and foreign keys to daily_log.user_id.
5. Analytics Dashboard – Query daily_log_item counts per status, time spent per day, etc.

---

Step 7 – Development Milestones

Step	Deliverables	Notes
Step 7.1 – Scaffold	Flask app skeleton, database config, migration scripts.	No UI yet.
Step 7.2 – Data Model	daily_log & daily_log_item tables, relationships.	Run migrations, seed a test log.
Step 7.3 – Daily‑Log UI	Two‑column layout, editable fields, save button.	Test on mobile emulation.
Step 7.4 – Settings & Accessibility	Color scheme toggle, font size slider, WCAG compliance.	Verify contrast with a tool.
Step 7.5 – All‑Logs List	Date list view, navigation to individual logs.	Add pagination if logs > 30 days.
Step 7.6 – Export / Import	JSON export button, import form.	Validate with sample data.
Step 7.7 – Future‑Feature Placeholders	“Coming Soon” cards in right column.	Keep UI ready for Calendar & Task List.
Step 7.8 – Testing & QA	Unit tests for models, integration tests for routes.	Ensure data integrity.
Step 7.9 – Deployment	Dockerfile, production config, environment variables.	Prepare for scaling.

---

Step 8 – Success Criteria

Criteria	How to Measure
Usability	User can create, edit, and view a log in < 30 s on a phone.
Accessibility	Passes automated WCAG 2.1 AA audit (contrast, ARIA).
Performance	Page loads < 1 s; DB queries return < 200 ms.
Extensibility	Adding a new feature (e.g., a “Mood Chart”) requires only a new table and minimal code changes.
Data Integrity	No orphaned daily_log_item rows after deleting a log.

---

Next Steps

1. Confirm that the “Step” labels meet your needs.
2. If any additional fields (e.g., priority on daily_log_item) are required, note them now.
3. Hand this blueprint to your developer or use it to start writing migration scripts.

Feel free to ask for any clarification or deeper dives into a particular step!