← Coffee Compass

Download the Markdown ↓

Coffee Compass — Vision & Build PRD

A build-it-yourself product brief for an AI-assisted Fellow Aiden brew-profile companion.

Scope. This document is a build specification, not a supported software distribution. It provides the product model, requirements, sequencing, and implementation lessons needed to create your own version. Your resulting application, technology choices, security posture, deployment, and maintenance remain yours.

Version: 1.1 — complete. Covers the everyday tool, two-way device sync, profile materialization, self-grounding on your own profiles, and the Brew Log. Built and running. Audience: a Fellow Aiden owner who wants to build their own version, with their own AI coding agent, on whatever stack they prefer.

How to use this document

This is a product requirements + vision brief, not a codebase. Hand it to a capable AI coding agent (or read it and build by hand). It describes what the tool does and how the pieces fit, plus the hard-won facts about the Fellow Aiden integration that will save you days. It deliberately avoids prescribing a language, framework, database, or model: those are yours to choose. Where a decision matters, the brief explains the reasoning so you can adapt it to your needs rather than copy ours.

There is no repository and no shared code by design. The goal is for you to build something that fits your taste, your coffees, and your setup, grounded in your data, rather than inherit assumptions baked into someone else's build.

Why a PRD instead of a repository

This is a deliberate choice, not laziness about packaging.

Software is trending toward disposable and single-use. A great deal of what gets published as a repo is something almost no one else will actually run, because running someone else's build means trusting it. And trust is the real obstacle here: this tool holds your account credentials, talks to a reverse-engineered API, and can create and delete things on a physical device. Reasonable people are skeptical of letting an unfamiliar codebase touch any of that. No one wants a stranger's project taking down their home server, burning their API access, or quietly opening a backdoor.

A PRD sidesteps all of it. You hand this brief to an agent you already trust, in an environment you control, and it builds something you can read and own end to end. You adapt the data model to your coffees, swap the model for whatever you run, and decide your own safety posture. You get the design and the hard-won integration knowledge without importing anyone's dependencies, assumptions, or risk. The thing you end up with is yours, not a fork of ours.

If you build something good from this, that is the entire point. There is nothing to star and no one keeping score.

The problem

The Fellow Aiden brews wonderfully once a profile is dialed in, but dialing in is a craft, and the results are fragile:

The vision

A personal companion that:

  1. Keeps a library of the coffees you brew, with the details that matter for brewing.
  2. Generates and refines Aiden brew profiles with an AI model, grounded in real brewing principles and in a model of your taste that learns from your feedback.
  3. Acts as the durable home for your profiles, beyond the device's 14-slot limit, and reconciles cleanly with the machine in both directions.
  4. Stays personal and private: your data, your palate, your device. No accounts to create for anyone else, no telemetry, no publishing.

It is explicitly a single-user, personal tool. That keeps the design honest and small.

Core capabilities

Each capability below is described as an outcome, not an implementation.

1. Coffee library

Track the coffees you brew: name, roaster, origin, process, variety, roast level, flavor notes, a rating, and free notes. Support adding a coffee by pasting a product URL or a block of text and letting the AI extract the structured fields (never fabricating; leaving blanks when a fact is not present). Warn when a coffee name already exists.

2. AI profile generation, grounded

Generate a complete Aiden brew profile for a coffee. Two inputs make the output good rather than generic:

The model returns a structured profile (the exact field set is in "The Aiden profile" below) plus a short rationale. Validate every value against the device's allowed ranges before trusting it.

3. The iteration loop

Refining matters more than first-shot generation. Support:

4. Brew logging and taste learning

After brewing, log the result with structured flags (too thin, too bitter, too astringent, too bold, perfect, etc.) and an optional rating. Each logged brew nudges the taste model by a small, bounded amount and records the evidence (the "why") so the learning is transparent and correctable. Keep this visible on a "taste model" page where the user can see every dimension, the evidence behind it, and edit any value directly. Small bounded nudges (for example ±0.25 on the 0–10 scale, clamped) beat large swings; the point is gentle drift toward truth, auditable at every step.

5. Push a profile to the Aiden + share

Send a generated profile to the device so it appears in the official app, ready to brew. Optionally generate a shareable link and QR code for it. (See "Fellow integration reality".)

6. Two-way sync and a durable archive

Pull every profile down from the account into a durable archive, and manage which of your custom profiles are on the device. This is where the 14-slot problem gets solved and where your library becomes the source of truth. The full model is in "Lifecycle and sync".

The Aiden profile (data contract)

A profile the device accepts has exactly these fields. Temperatures are in Celsius. This is the single most important and least obvious fact: the official app shows Fahrenheit, but the API speaks Celsius, on a half-degree grid. If you send Fahrenheit values they will be rejected (they fall outside the allowed range).

Field Type Allowed values
profileType int 0 for a standard custom profile
title string up to 50 characters
ratio number 14 to 20, step 0.5 (coffee-to-water; advisory for some users)
bloomEnabled bool
bloomRatio number one of {1, 1.5, 2, 2.5, 3}
bloomDuration int 1 to 120 (seconds)
bloomTemperature number 50 to 99 °C, step 0.5
ssPulsesEnabled bool single-serve
ssPulsesNumber int 1 to 10
ssPulsesInterval int 5 to 60 (seconds)
ssPulseTemperatures number[] each 50–99 °C step 0.5; array length equals ssPulsesNumber
batchPulsesEnabled bool
batchPulsesNumber int 1 to 10
batchPulsesInterval int 5 to 60 (seconds)
batchPulseTemperatures number[] each 50–99 °C step 0.5; array length equals batchPulsesNumber

Conversion: C = (F − 32) × 5/9, then snap to the nearest 0.5 and clamp to [50, 99]. Example: 195 °F becomes 90.5 °C; 198 °F becomes 92.0 °C.

A note on the coffee-to-water ratio: keep it in the contract because most people want it, but be aware some users (including ours) ignore it and dose grounds by hand, because the machine will not let them dose as much coffee as they want. Treat it as advisory, not a bug.

Fellow integration reality (the part worth reading twice)

There is no official public API. There is a cloud API the mobile app uses, and the community has reverse-engineered it. You can talk to it directly or use a community client library. The behavior below is what we learned the hard way; expect it to drift as Fellow updates things.

Authentication. Log in with the account email and password and you get a bearer token (plus a refresh token). Treat these as secrets: keep credentials in environment configuration, never in code, and do not log the auth response — some community clients print it at debug level, tokens and all. Silence that.

Endpoints (shape, not a contract). Roughly: a login endpoint; a "devices" endpoint that returns your brewers; per-device "profiles" endpoints to list, create, and delete; and a per-profile "share" endpoint that returns a shareable link. The base is an AWS API Gateway host that community clients already know; rather than hardcode a URL that may rotate, discover it from a current community client.

Two traps that will break a naive client (these cost us real time):

  1. The device object no longer embeds the profile list. Older clients assume the device record contains profiles and schedules arrays and crash on construction when those keys are absent. Fetch the profile list from the dedicated profiles endpoint instead, and read only the brewer id from the device record.
  2. Delete validates against that same list. A delete-by-id call checks the id against the client's internal profile list before issuing the delete. If you left that list empty (because of trap 1), every delete fails with "profile does not exist." Populate the profile list from the endpoint and deletes work.

Sharing is server-side, and the QR is just the link. When you request a share for a profile, the cloud returns a single thing: a brew.link URL (we confirmed the response payload is literally { "link": "https://brew.link/p/…" }, nothing more). There is no separate QR image from the API. The QR code you see is simply that URL encoded as a square: the brew.link page and the Fellow app's share screen render one, and you can equally render your own from the link to show in your tool or print on a coffee bag. Scanning it opens the profile in the Brew with Aiden app. You create the profile on the account first, then request its link; you cannot construct a brew.link URL offline from settings.

The device holds 14 profiles; the cloud holds more. This asymmetry is the whole reason the archive and the managed-sync model exist.

Profiles get a server-assigned id when created (and a new id if you delete and recreate). Do not treat that id as stable identity (see "Lifecycle and sync").

Conceptual data model

Described as entities and the fields that carry meaning. Use whatever storage you like.

Lifecycle and sync (the heart of the design)

This is the most reusable idea in the whole project, and it is fully stack-agnostic. Treat the relationship between your library and the device as desired state plus an explicit apply, the same shape as infrastructure tooling's "plan / apply".

The coffee is the unit; everything is one set in three states. Resist the temptation to model "your coffees" and "the device profiles" as two separate worlds — users don't think that way. A coffee is either On device, in the Queue (staged to move), or in the Archive (off device, kept). "Not on the device" simply is "archived." The device view should show your whole coffee set, bucketed by state — not a separate list of device-only profiles. Link each coffee to its device profile with a stable id (not name-matching — coffees collide on origin words like "Peru"); a coffee with no device profile yet is just an archived coffee you haven't dialed for.

Two independent axes drive the buckets:

These are different things and should not be collapsed into one checkbox. One is a wish, the other is a fact.

The queue is the difference between them, derived live (never stored):

on device not on device
active On device — in sync Queue: ADD — push on next sync
archived Queue: REMOVE — delete on next sync Archive — off device, kept

Elevating a coffee from Archive makes it active → it shows as a queued ADD. Archiving an on-device coffee makes it archived → a queued REMOVE; after apply it drops into the Archive. A coffee with no device profile at all is in the Archive too — to elevate it you dial a profile first (there's nothing to load otherwise).

Apply is manual and ordered. When the user syncs, process REMOVES before ADDS. Even though the desired set is capped at 14, the device may currently hold 14; removing first frees a slot so an add never transiently pushes the device to 15 and gets rejected. So the real-world swap is explicit: archive one (queues a remove), sync, the remove runs first, then the add.

Two stable links keep identity straight. (1) Each device profile points at its coffee by a stable id, so the device view can bucket the one coffee set — never match coffee↔profile by name (origin words like "Peru" collide and mis-link). (2) The server-assigned profile id is just a pointer to whatever is currently on the device: set it on push, cleared on remove. Because delete-then-recreate yields a new server id, keying identity on the server id would spawn duplicates; keying on your local ids (and relinking when a recreated profile reappears) does not. Expect a few device profiles that aren't in your coffee history yet — give them coffee cards so every profile has a home.

Safety boundaries:

Suggested build order

We built it in this order and it worked well, because each phase ships value and de-risks the next:

  1. Library + AI generation + iteration loop + brew logging + taste learning. The everyday tool, before any device integration.
  2. Push a profile to the device + share link/QR. First contact with the Fellow API. Expect the Celsius conversion and the two client traps here.
  3. Pull + archive (memorialization). Read-only with respect to the device. This alone solves the 14-slot fear: your library outlives any eviction.
  4. Managed customs: active/archive, the derived queue, manual apply (with the remove-before- add ordering and the 14-cap guard). The two-way sync.
  5. A "generate → queue" bridge, so a freshly generated profile flows into the queue rather than being pushed immediately. One path, not two.
  6. (Planned) Grounding the AI in your real, dialed-in profiles, so refinement reasons from what is actually on your machine, not from seed approximations. The "refinement tour" section will document this once complete.

Roles you will need to choose

To keep this stack-agnostic, here are the roles, not our picks:

Principles that kept the build honest

Prior art and resources

You do not have to reverse-engineer the Fellow cloud API from scratch. The community has already done much of it:

On referencing these at all: they are public community work, not our build. Pointing you to them is the opposite of exposing a private codebase; it is the fastest way to stand on what already exists and then go your own way. If you would rather not depend on a community client, the API shapes and the gotchas documented above are enough to write a thin client of your own.

The refinement tour (calibrating the AI to your palate)

Covers the calibration method, the baseline, the validated before/after of grounding, and a stricter "names withheld" integrity check.

The roaster's published profile is generic by necessity. The whole value of a personal tool is dialing in to your taste, and if you are an established brewer you already hold the answer key: your own dialed-in profiles. This section is a repeatable way to teach the model your own approach and verify it, useful even if you do not do this kind of work for a living.

Two stages, on purpose:

  1. Known / named calibration (names can bleed in). Generate a profile while giving the model the coffee's name and attributes. Be aware that the name, and any reference profiles you feed the model, can bleed into its reasoning: it may lean on what it already "knows" about a well-known coffee rather than reason purely from character. That is fine for a first pass; it tends to produce a sensible, close, but generic result. You compare that result against your real device settings to see the gap.
  2. Blind refinement (force independent reasoning). Withhold the dialed-in recipe (and, for a stricter test, the name too), leaving only character: origin, process, roast, tasting notes, plus your taste model. This removes the bleed and tests whether the model has actually learned your taste rather than recognized a coffee. The gap closing here is the real proof.

Baseline finding (stage 1, recipe withheld, name given), against three dialed-in profiles:

What grounding changed (validated). We then supplied the user's real dialed-in profiles as worked examples in the generation context, excluding the coffee being profiled so a blind take stays honest, and re-ran the same three coffees:

So the arc is: the profile structure was free; calibration against your own profiles fixes the systematic bias and captures your per-coffee patterns; and the feedback loop handles the outliers. That is the whole point of a personal tool, and it only works because your dialed-in profiles are the answer key.

Hard mode: names withheld (the integrity check). To confirm the model was reasoning from character and the user's own taste rather than recognizing a known coffee, we re-ran with the coffee name and roaster removed entirely (only origin, process, roast, and tasting notes given), the same coffee still excluded from the examples, and the seed library reference turned off so the only profile signal was the user's own dialed-in profiles. It held up: outputs still landed in the user's real neighborhood (bloom within a few degrees, correct structure). On the character-rich coffee it actually got closer with no name at all. Two honest caveats surfaced: where character was thin (a vague blend), the model leaned hardest on the user's central tendency and drifted from that coffee's atypical setting; and where the name had been carrying a real decision (one coffee's extra pulse), removing it lost that detail. The practical guidance: give the name in normal use — identity is legitimate signal — and let grounding plus character do the rest. The nameless run is a validation tool, not the recommended mode.

Second case study: low-feedback coffees vs the user's curated profiles. We later ran the same blind comparison on six coffees the user had only lightly refined (and for which the user supplied a curated "best-known" profile each, with a self-assigned confidence tag). The result sharpened the picture: on a conventional coffee the grounded model nailed the bloom and came within a degree or two on pulses; but on coffees where the user makes unusual choices it diverged predictably — it stayed near its ~188-190°F bloom comfort zone where the user blooms much cooler (176-184°F), it preferred four batch pulses where the user runs five, and it could not reproduce an idiosyncratic ascending pulse ramp the user had dialed by hand. The lesson: grounding reliably lands the well-trodden coffees, but a user's hard-won, atypical choices on lightly-explored coffees are theirs — the model gives a sensible generic, not a clone. This is exactly why the user's own stored profiles (and a confidence tag noting how much a profile was refined) matter: trust the user's value over the model's where the two disagree on a low-confidence, idiosyncratic coffee.

The takeaway for a builder: do not judge the AI only on first-shot generation. Build the calibration loop (generate, compare to your real settings, feed your reals back as examples, re-compare). The structure comes for free; your palate is what you are teaching.

Scaling the examples. Feed the model the dialed-in profiles most similar to the coffee being profiled first (rank by shared origin, process, roast, and tasting-note terms), and only truncate the list once the library is large. Two cautions learned the hard way: keep the cap generous, because a coffee with no close precedent still benefits from the full breadth of your experience, and do not over-read a single generation, because a model run at a low temperature still wobbles a few degrees run to run. You are aiming the starting point into the right neighborhood, not hitting an exact number on the first try.

Getting smarter over time (without fine-tuning)

The goal is to stop reaching for an outside model to get good profiles. The path is layered, and none of it is weight training:

  1. Grounding self-improves as the library grows (passive, biggest lever). Every coffee the user dials adds a real worked example; similarity-ranking surfaces the closest ones. More of the user's actual profiles = less drift to the generic middle.
  2. Encode measured tendencies as explicit guidance (active). Mine the user's real profiles for their structural habits (bloom temp by roast, bloom-ratio and pulse-count preferences) and state them as rules in the principles. This corrects systematic biases the examples alone don't (the model averaging to a median instead of, say, cooling the bloom for sweet-protection).
  3. The Brew Log feedback loop (compounding, per-coffee). Tasting notes and dial-in events accumulate and ground future regens; structured brew feedback nudges the taste model.

A measured caveat: idiosyncratic, hand-built structures (an unusual ascending pulse ramp) the model will not invent — those stay the user's stored values. Trust the user over the model where they disagree on a low-confidence, atypical coffee. Fine-tuning is not worth it at personal scale; in-context grounding plus encoded tendencies captures the value with none of the cost.

Working with your AI agent (starter prompts)

This brief is meant to be handed to an AI coding agent, not read like a manual. Below is a sequence of starter prompts that mirrors the suggested build order. Paste the whole brief into your agent first, then drive it phase by phase. Adapt the bracketed parts to your stack and your coffees. These are a starting point, not a script.

0. Orient the agent and choose your stack.

I'm giving you a product brief for a personal Fellow Aiden brew-profile tool. I want to build my own version for myself. My environment is [language / framework / database / model]. Read the whole brief, then propose an architecture and a phase-1 plan that follows the suggested build order. Flag anywhere my stack changes the brief's assumptions, and ask me anything you need before you write code.

1. The everyday tool first (library, generation, iteration, logging).

Build phase 1 from the brief, with no device integration yet: the coffee library and the conceptual data model, the add-a-coffee flow (paste a product URL or text and extract the structured fields, never fabricating, leaving blanks when a fact is absent), AI profile generation, the iteration loop, and brew logging. Generate the schema and the core screens.

2. Ground the model in real principles and a taste model.

Wire in two grounding inputs from the brief: a brewing-principles reference, and a taste model with the preference dimensions and tolerances on a 0–10 scale. Generate a complete profile plus a short rationale, and validate every value against the device data contract (Celsius, the half-degree grid, the allowed ranges) before trusting the output.

3. Teach it what I actually like, from my own dialed-in profiles.

Here are [N] of my dialed-in profiles [paste them]. Build my taste model from them and mine my structural tendencies — typical bloom temperature by roast level, bloom-ratio and pulse-count habits — and state those as explicit guidance in the generation context. When you generate for a coffee, feed the most similar of my profiles first (rank by shared origin, process, roast, and tasting-note terms).

4. Prove it learned, the blind way.

Add a "blind take": generate a profile without showing the model my existing recipe, then show me the gap against my real settings. Then run a leave-one-out across all my profiles — hide each coffee's real recipe, predict it from character plus my taste model and my other profiles, and report how close it lands. I want to see whether it's actually reasoning from my taste and my real profiles, or just echoing my seed data.

5. Connect to the Aiden (mind the traps).

Implement the Fellow cloud client per the "Fellow integration reality" section. Watch the two traps: fetch the profile list from the dedicated profiles endpoint (the device object no longer embeds it), and populate the client's internal profile list before any delete or deletes fail. Keep credentials in environment config, never in code, and do not log the auth response. Push a profile to the device and request its share link / QR.

6. Solve the 14-slot problem, then sync both ways.

Implement pull + an append-only archive first (read-only with respect to the device — this alone outlives any eviction). Then build the managed sync from the brief: desired state (active vs archived, capped at 14) versus observed state (on-device or not), the queue derived live as the difference, and a manual, confirmed apply that processes removes before adds.

A few cautions worth pasting when relevant:

Don't over-read a single generation — even a low-temperature run wobbles a few degrees run to run; you're aiming the starting point into the right neighborhood, not hitting an exact number. And where the model and one of my hard-won, atypical profiles disagree on a low-confidence coffee, trust my stored value over the model's.

This brief documents the project through two-way device sync, the calibration method, grounding, the Brew Log, and how the model improves over time.