Skip to content

Commit fd4fa21

Browse files
loicleflochloiclefloch
committed
post: building-inkwell-with-bmad
1 parent ba992a6 commit fd4fa21

10 files changed

Lines changed: 2644 additions & 0 deletions

‎source/_posts/building-inkwell-with-bmad-brainstorming-session.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: "Building Inkwell with BMAD: BMAD output files - Brainstorming Session"
3+
date: 2026-01-08 23:03:00
4+
permalink: /building-inkwell-with-bmad/output/brainstorming-session
5+
description: "Output file of the BMAD method for the Brainstorming Session."
6+
tags: [bmad, obsidian, development, spec-driven-development, methodology]
7+
hidden: true
8+
---
9+
10+
>This post contains the output of the BMAD Method "Product Requirements Document" for my Inkwell project. Inkwell is a read-it-later app optimised for my workflow and that works on my e-reader.
11+
>I made a [blog post about how I built a project using AI and BMAD Method](/building-inkwell-with-bmad)
12+
13+
<br />
14+
Path: _bmad-output/analysis/brainstorming-session-2026-01-06.md
15+
<br />
16+
The file begins with a markdown Front Matter metadata header:
17+
18+
```markdown
19+
---
20+
stepsCompleted: [1]
21+
inputDocuments: []
22+
session_topic: 'New product ideation with emphasis on technical simplicity and maintainability'
23+
session_goals: 'Generate product concepts that are technically simple to build and maintain'
24+
selected_approach: 'AI-Recommended Techniques'
25+
techniques_used: []
26+
ideas_generated: []
27+
context_file: ''
28+
---
29+
```
30+
31+
# Brainstorming Session Results
32+
33+
**Facilitator:** Loic
34+
**Date:** 2026-01-06
35+
36+
## Session Overview
37+
38+
**Topic:** New product ideation with emphasis on technical simplicity and maintainability
39+
**Goals:** Generate product concepts that are technically simple to build and maintain
40+
41+
### Session Setup
42+
43+
Based on our discussion, we've established clear parameters for this brainstorming session. The focus is on identifying product opportunities that balance innovation with technical feasibility, ensuring long-term maintainability and ease of implementation.
44+
45+
---
46+
47+
You can see the other outputs [here](/building-inkwell-with-bmad/output/) and the [blog post about how I built a project using AI and BMAD Method](/building-inkwell-with-bmad).

‎source/_posts/building-inkwell-with-bmad-epics.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
title: "Building Inkwell with BMAD: BMAD output files - Product Epics"
3+
date: 2026-01-08 23:03:00
4+
permalink: /building-inkwell-with-bmad/output/epics
5+
description: "Output file of the BMAD method for the product epics."
6+
tags: [bmad, obsidian, development, spec-driven-development, methodology]
7+
hidden: true
8+
---
9+
10+
>This post contains the output of the BMAD Method "Product brief" for my Inkwell project. Inkwell is a read-it-later app optimised for my workflow and that works on my e-reader.
11+
>I made a [blog post about how I built a project using AI and BMAD Method](/building-inkwell-with-bmad)
12+
13+
<br />
14+
Path: _bmad-output/planning-artifacts/epics.md
15+
<br />
16+
The file begins with a markdown Front Matter metadata header:
17+
18+
```markdown
19+
---
20+
stepsCompleted: [1, 2]
21+
inputDocuments:
22+
- _bmad-output/planning-artifacts/prd.md
23+
- _bmad-output/implementation-artifacts/tech-spec-inkwell-mvp-e2e.md
24+
---
25+
```
26+
27+
# inkwell - Epic Breakdown
28+
29+
## Overview
30+
31+
This document provides the complete epic and story breakdown for inkwell, decomposing the requirements from the PRD and Tech Spec into implementable stories.
32+
33+
## Requirements Inventory
34+
35+
### Functional Requirements
36+
37+
**FR1:** System shall provide Telegram bot integration that accepts article URLs from any device and displays queued links in chat
38+
39+
**FR2:** System shall connect to user's Obsidian vault GitHub repository and read markdown files from `1. Inbox/clippings/` folder
40+
41+
**FR3:** System shall detect and display articles tagged with both `#clippings` AND `#to-read` tags
42+
43+
**FR4:** System shall provide a server-side rendered web reading interface optimized for e-ink displays
44+
45+
**FR5:** System shall display an article list view showing title, date saved, and source for all to-read articles
46+
47+
**FR6:** System shall provide one-tap "Mark as Read" functionality that removes `#to-read` tag from article frontmatter
48+
49+
**FR7:** System shall update markdown file tags locally via GitHub API when articles are marked as read
50+
51+
**FR8:** System shall require user authentication via username/password to access reading interface
52+
53+
**FR9:** System shall sync articles from GitHub on page load (no real-time webhooks)
54+
55+
**FR10:** System shall render full markdown content with clean typography optimized for e-ink devices
56+
57+
**FR11:** System shall provide responsive design that works on Boox browser, mobile, and laptop devices
58+
59+
**FR12:** System shall validate URLs before adding to Telegram queue
60+
61+
### Non-Functional Requirements
62+
63+
**NFR1:** System shall load pages via SSR in under 2 seconds on e-ink devices
64+
65+
**NFR2:** System shall implement in-memory caching with 15-minute TTL to respect GitHub API rate limits (5000 requests/hour)
66+
67+
**NFR3:** System shall use HTTP-only secure cookies for session management with 30-day expiration
68+
69+
**NFR4:** System shall sanitize all markdown HTML output to prevent XSS vulnerabilities
70+
71+
**NFR5:** System shall require maximum few hours per month maintenance burden
72+
73+
**NFR6:** System shall be built with TypeScript in strict mode throughout the codebase
74+
75+
**NFR7:** System shall use minimal UI chrome to reduce e-ink screen repaints
76+
77+
**NFR8:** System shall disable animations and transitions for e-ink optimization
78+
79+
**NFR9:** System shall handle GitHub API rate limiting gracefully with proper error messages
80+
81+
**NFR10:** System shall provide structured logging using Pino for debugging and monitoring
82+
83+
**NFR11:** System shall deploy to fly.io with simple one-command deployment
84+
85+
**NFR12:** System shall achieve 80% reading completion rate and 5+ days per week usage within first month
86+
87+
### Additional Requirements
88+
89+
**Architecture & Technical Requirements:**
90+
91+
- **AR1: Starter Template** - React Router v7 greenfield project using `npx create-remix@latest` with TypeScript template
92+
- **AR2: Technology Stack** - React Router v7, TypeScript, Tailwind CSS, shadcn UI, Octokit, Telegraf, gray-matter, marked, bcrypt, fly.io
93+
- **AR3: Data Model** - Articles stored as `.md` files in `1. Inbox/clippings/` with frontmatter format `tags: [clippings, to-read]`
94+
- **AR4: Authentication Strategy** - Session-based auth with secure HTTP-only cookies using `createCookieSessionStorage`
95+
- **AR5: GitHub Integration** - Use GitHub REST API with personal access token, implement FIFO cache with 100-entry limit, 15-minute TTL
96+
- **AR6: Telegram Integration** - Webhook-based bot with in-memory queue (acceptable data loss on restart)
97+
- **AR7: File Structure** - React Router v7 conventions with `app/routes/` for file-based routing, `*.server.ts` for server-only code
98+
- **AR8: E-ink Styling** - Tailwind config with high contrast colors, Georgia serif font, disabled animations/transitions
99+
- **AR9: Environment Variables** - Requires GITHUB_TOKEN, GITHUB_OWNER, GITHUB_REPO, GITHUB_BRANCH, TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET, SESSION_SECRET, AUTH_USERNAME, AUTH_PASSWORD_HASH, LOG_LEVEL, NODE_ENV
100+
- **AR10: Security Implementation** - Telegram webhook signature validation using secret token, bcrypt for password hashing, HTML sanitization
101+
- **AR11: Error Handling** - Graceful degradation for GitHub API failures, 404 handling, rate limit monitoring
102+
- **AR12: Deployment** - fly.io with Dockerfile auto-generation, health check endpoint at `/healthz`, Paris region (cdg)
103+
- **AR13: Code Patterns** - Singleton pattern for API clients, TypeScript interfaces for all data models, loader/action functions for SSR
104+
- **AR14: Testing Strategy** - Manual testing only for MVP on actual Boox device
105+
106+
### FR Coverage Map
107+
108+
**FR1:** Epic 4 - Telegram bot for link capture
109+
**FR2:** Epic 3 - GitHub vault connection
110+
**FR3:** Epic 3 - Tag-based article detection
111+
**FR4:** Epic 3 - SSR reading interface
112+
**FR5:** Epic 3 - Article list view
113+
**FR6:** Epic 3 - Mark as read functionality
114+
**FR7:** Epic 3 - GitHub API tag updates
115+
**FR8:** Epic 2 - User authentication
116+
**FR9:** Epic 3 - Page-load GitHub sync
117+
**FR10:** Epic 3 - Markdown rendering
118+
**FR11:** Epic 3 - Responsive design
119+
**FR12:** Epic 4 - URL validation
120+
121+
## Epic List
122+
123+
### Epic 1: Project Foundation & Infrastructure
124+
125+
Development environment is set up with all core infrastructure, enabling rapid feature development with type safety, e-ink optimization, and deployment capabilities.
126+
127+
**FRs covered:** None directly (foundational)
128+
**NFRs covered:** NFR6, NFR11
129+
**ARs covered:** AR1, AR2, AR7, AR8, AR9, AR12, AR13, AR14
130+
131+
### Epic 2: Secure Access & Authentication
132+
133+
As Loic, I can securely log into the reading interface from my Boox e-reader, ensuring my private Obsidian content is protected while maintaining persistent sessions across reading sessions.
134+
135+
**FRs covered:** FR8
136+
**NFRs covered:** NFR3
137+
**ARs covered:** AR4, AR10
138+
139+
### Epic 3: Article Discovery & Reading
140+
141+
As Loic, I can view all my to-read articles from my Obsidian vault, read them comfortably on my Boox e-reader with clean typography, and mark articles as read when finished, with changes persisting back to my vault.
142+
143+
**FRs covered:** FR2, FR3, FR4, FR5, FR6, FR7, FR9, FR10, FR11
144+
**NFRs covered:** NFR1, NFR2, NFR4, NFR7, NFR8, NFR9, NFR10
145+
**ARs covered:** AR3, AR5, AR11
146+
147+
### Epic 4: Cross-Device Link Capture
148+
149+
As Loic, I can capture article links from my phone or any device by sharing them to a Telegram bot, which queues them for later processing through my existing Obsidian Web Clipper workflow.
150+
151+
**FRs covered:** FR1, FR12
152+
**NFRs covered:** None directly
153+
**ARs covered:** AR6, AR10
154+
155+
### Epic 5: Production Readiness & Monitoring
156+
157+
As Loic, I have confidence that the tool is reliable, maintainable, and performs well in production, with health monitoring and error visibility for quick troubleshooting.
158+
159+
**FRs covered:** None directly (operational)
160+
**NFRs covered:** NFR5, NFR12
161+
**ARs covered:** AR12
162+
163+
164+
---
165+
166+
You can see the other outputs [here](/building-inkwell-with-bmad/output/) and the [blog post about how I built a project using AI and BMAD Method](/building-inkwell-with-bmad).

‎source/_posts/building-inkwell-with-bmad-output.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: "Building Inkwell with BMAD: BMAD output files"
3+
date: 2026-01-08 23:03:00
4+
permalink: /building-inkwell-with-bmad/output
5+
description: "Output files of the BMAD method."
6+
tags: [bmad, obsidian, development, spec-driven-development, methodology]
7+
hidden: true
8+
---
9+
10+
>This post contains the output of the BMAD Method for my Inkwell project. Inkwell is a read-it-later app optimised for my workflow and that works on my e-reader.
11+
>I made a [blog post about how I built a project using AI and BMAD Method](/building-inkwell-with-bmad)
12+
13+
<br />
14+
You will find the different markdown files that has been created by this spec-driven development method.
15+
<br />
16+
<br />
17+
18+
# Brainstorming Session
19+
20+
[Open the file](/building-inkwell-with-bmad/output/brainstorming-session)
21+
22+
# Product Brief
23+
24+
[Open the file](/building-inkwell-with-bmad/output/product-brief)
25+
26+
# PRD (Product Requirements Document)
27+
28+
[Open the file](/building-inkwell-with-bmad/output/prd)
29+
30+
# Tech Specs
31+
32+
[Open the file](/building-inkwell-with-bmad/output/tech-specs)
33+
34+
# Epics
35+
36+
[Open the file](/building-inkwell-with-bmad/output/epics)

0 commit comments

Comments
 (0)