Decisions
Decision records from the FRIDAY build and from this site, each written as context, constraints, decision, trade-offs and outcome.
Tag private context by hand (accepted)
FRIDAY is a local-first AI assistant designed to route each request to a local model or to Claude. Some of what I ask about is private, so the system had to decide, request by request, what was allowed to leave my Mac.
Constraints
- Private context has to stay on the machine even when a cloud model would answer better.
- The local model has to be small enough to run alongside everything else on a laptop.
Decision
Context is tagged private by hand, with no automatic guessing. Any request carrying private context is rewritten to the local model, and the cloud path refuses by default. I built this boundary before any feature, so every later feature inherited it instead of having it retrofitted.
Trade-offs
- A manual tag asks more of me than automatic detection would, and a tag I forget is a gap the rule cannot see. In exchange, the system never decides on its own that private context is safe to send.
Outcome
In version 1, privacy was structural: the routing layer enforced it, and the cloud path refused by default.
Relative-margin rule instead of a similarity threshold (accepted)
FRIDAY's first version pruned weak notes before answering. I calibrated a similarity threshold for that on my real notes, and the scores did not separate cleanly.
Constraints
- Off-topic scores (0.69 to 0.78) overlapped genuine ones (0.73 to 0.80).
- Any threshold strong enough to prune could also drop a private note and push a private request to the cloud.
Decision
Dropped the threshold and replaced it with a relative-margin rule. The same set of notes then drove both the answer and the privacy decision, so the two could not disagree.
Trade-offs
- The scores were measured on my own notes, which is the corpus the rule has to work on.
Outcome
The answer and the privacy decision come from one set of notes, so pruning cannot quietly turn a private request into a cloud one.
Defer the warm cloud session (deferred)
Keeping a warm cloud session would have made FRIDAY's replies faster.
Constraints
- A warm session carried context across sessions, which cuts against the privacy boundary.
Decision
Deferred it. Correctness came before latency.
Trade-offs
- Replies are slower than they could be.
Outcome
The privacy rule is not weakened for speed.
No CMS (accepted, 2025-01)
Content management systems like Contentful or Sanity are common for portfolio sites. The question was whether the overhead is justified.
Constraints
- Content changes happen a few times per year, not daily.
- A CMS adds a deployment dependency: the site breaks if the API is down.
- All content is structured data (projects, skills, career history), not freeform prose.
Decision
All content lives in JavaScript files (architectureCases.js, careerData.js, skills data). The content is imported with the app, needs no API call and is versioned in Git.
Trade-offs
- Content changes require a code commit and deploy, but this takes under a minute.
- No non-developer editing, but there is only one author.
- No content preview, but the dev server is the preview.
Outcome
Content has no external dependency and sits under version control with the code that renders it.
Architecture case study format (accepted, 2025-01)
Most portfolios show projects as screenshots with bullet points. The question was how to present project work in a way that demonstrates engineering thinking.
Constraints
- The differentiator is the process behind the output, so viewers should see how each decision was made.
- Content must be factual and tied to real project work (university submissions).
- The format must be consistent across all projects for comparability.
Decision
Every project uses the same five-section structure: Context, Constraints, Decisions, Trade-offs, and Outcome. This mirrors how the projects were actually reasoned about during development. The structure is a data format (architectureCases.js), not just a layout choice.
Trade-offs
- More verbose than a simple project card, but the depth is the point.
- Requires discipline to keep consistent, but with five case studies this is manageable.
Outcome
Each case can be read as a record of how its decisions were made, in the same shape every time.
Contact email through a server-side handler (accepted, 2025-06)
The contact page has a form that needs to send email. The options were: a client-side email service (keys in the browser), a standalone backend, or a request handler running alongside the site. An earlier version used a client-side service, which put the API key in the browser; it was replaced once the site gained a server-side runtime.
Constraints
- The email provider's API key must stay server-side. It cannot ship in client code.
- The handler must stay host-portable: the same (req, res) function runs as a serverless function or under Express, so changing host doesn't mean rewriting it.
- The form sends only a handful of emails per month, so cost and scale are non-issues.
Decision
The form POSTs to a server-side handler (/api/contact) that sends the message through Resend, with the API key held server-side in an environment variable. If the backend is unconfigured or unavailable (503/502), the frontend falls back to a mailto: link so a message always has a path.
Trade-offs
- Third-party dependency on Resend, but only for a non-critical feature with a built-in mailto fallback.
- Adds a server-side endpoint, but it sits alongside the same app's analytics and guestbook handlers, so there is no separate service to run.
Outcome
The API key stays on the server. The form uses the same Node process as the site and falls back to an email link when the backend is unavailable.