Architecture
Design decisions
Six choices that shaped SS-1. Each decision documents the question asked, the choice made, the reasoning, and the alternatives that were considered and rejected. These are the decisions worth explaining in a senior product interview.
Should the project context live in a database or a markdown file?
Decision
A local markdown file under git version control — the Project Manifest.
Why
A markdown file gives you three things a database does not: a human-readable document that a PM can edit directly, a git diff that shows exactly what changed, and a commit history that is a narrative of how your competitive thinking evolved. The manifest is designed to be read by a person, not just queried by an agent. It also means the entire intelligence system is portable, inspectable, and auditable without any tooling beyond a text editor and git.
Alternatives considered
- —SQLite table per project (queryable, structured)
- —JSON config file (machine-readable, but not diffable in a useful way)
- —Notion or external document (too many dependencies, no offline access)
Known trade-offs
- △No structured querying — agents must parse markdown
- △Schema enforcement is soft — malformed manifests degrade agent quality
- △Merge conflicts possible if two sessions edit simultaneously
Should every manifest write require explicit user approval?
Decision
Yes. Every agent-proposed manifest change must pass through a HITL approval gate with a diff preview.
Why
An agent that updates your product strategy without asking is not an intelligence tool — it is noise that happens to be automated. The manifest represents your product thinking. If the agent is wrong (wrong significance score, misread competitive context, hallucinated implication), an unreviewed write corrupts your strategic record. The HITL gate is not a safety guardrail bolted on after the fact — it is the product. The brief is the output. The approval is the moment the user evaluates the agent's reasoning and owns the decision.
Alternatives considered
- —Auto-apply all agent suggestions above a confidence threshold
- —Require approval only for 'high severity' signals
- —Optimistic write with undo capability
Known trade-offs
- △Requires user attention — defeats value if user rubber-stamps everything
- △Async approval means manifest can be stale during a session
- △Dismiss fatigue if significance scoring is poorly tuned
Why a five-node LangGraph pipeline instead of a single agent with tools?
Decision
A typed LangGraph DAG with specialised nodes — each responsible for a single reasoning task.
Why
A single agent with tools tends to collapse all reasoning into one undifferentiated pass. The LangGraph approach forces separation of concerns: the Monitor Node knows nothing about significance scoring; the Significance Gate knows nothing about brief generation. This makes each node testable in isolation, debuggable by inspection of state at each checkpoint, and replaceable without rewriting the whole pipeline. The state object is a typed dict that flows through the graph — every input and output is observable.
Alternatives considered
- —Single Sonnet agent with Firecrawl and SQLite tools
- —Two-stage pipeline (gather / reason)
- —Streaming tool-use pattern with one model
Known trade-offs
- △More code to maintain — five node files vs one agent file
- △LangGraph state schema changes require updating all nodes
- △Harder to explain to non-technical stakeholders
Why use Haiku for routing and scoring, and Sonnet only for briefs?
Decision
Model assignment by task type: Haiku for classification and scoring, Sonnet for reasoning-intensive outputs.
Why
Brief generation is the core product value — it must be high-quality. Sonnet has the reasoning depth needed to produce a genuinely useful strategic implication, not a generic summary. Routing and scoring are pattern-matching tasks: does this signal score above 40? What is the user's intent? Haiku is faster and cheaper for these operations, and wrong answers are recoverable (a miscategorised signal is re-evaluated; a wrong brief is more costly). The model assignment is a deliberate product decision, not a cost optimisation.
Alternatives considered
- —Sonnet for everything (best quality, highest cost)
- —Haiku for everything (cheapest, lowest quality briefs)
- —Dynamic model selection based on signal complexity
Known trade-offs
- △Two model configurations to maintain
- △Haiku scoring errors can suppress valid signals
- △Sonnet latency means brief generation has a visible delay
Should SS-1 use real OSINT tools or mock data for the v1 demo?
Decision
Mock data for the portfolio demo. The pipeline architecture is identical to a production implementation.
Why
The portfolio value of SS-1 is the architecture and the reasoning, not the OSINT itself. A real Firecrawl integration adds API key management, rate limiting, scraping variability, and a dependency on external services that can fail during a demo. The mock pipeline is deterministic, reproducible, and showcases the complete end-to-end flow reliably. The code is structured so that swapping mock_data.py for a real Firecrawl integration is a single-file change.
Alternatives considered
- —Real Firecrawl integration with live URLs
- —Cached OSINT responses (reproducible but dated)
- —Synthetic data generated by Claude at demo time
Known trade-offs
- △Demo does not prove real OSINT capability
- △Mock scenario must be maintained separately from real data
- △May look like a toy to reviewers unfamiliar with the architecture
Why build a companion website alongside the desktop app?
Decision
A 5-page documentation site deployed to Vercel, documenting decisions, architecture, and workflow.
Why
A desktop app recorded in a demo video shows what the product does. A website shows that the builder understands why every decision was made. For portfolio purposes, the website is as important as the app — it demonstrates senior product thinking, architectural reasoning, and the ability to communicate technical decisions to a non-technical audience. It also makes the project searchable and sharable without requiring anyone to run the app locally.
Alternatives considered
- —README-only documentation
- —Notion workspace (not public, not searchable)
- —Video walkthrough only
Known trade-offs
- △Additional build surface to maintain
- △Content can become stale relative to the code
- △Extra time investment in writing and design