The project brief

Before writing any code, get clear on what you are building and for whom. This stage walks through the client brief in docs/client-brief.md, a hypothetical but realistic case study designed to mirror the kind of project you would take on for a paying client. By the end of it you know the user, the problem, the required product, the non-goals, and the single measurable outcome that defines success.

Every real project starts here. The brief may come from a client, a manager, or yourself; either way it is the reference point every later decision gets checked against.

daveebbelaar/document-copilot0:04:00

The client

Driftwood Capital is an independent equity research firm with roughly 40 analysts. They do not manage money. They sell deep research on US public companies to institutional clients (hedge funds, mutual funds, pension funds) under annual subscriptions, plus commissioned research and analyst calls. Each analyst covers around 15 companies in one industry.

Their value is condensation. Portfolio managers do not have the bandwidth to read every 10-K, 10-Q, and earnings transcript for the companies they hold, so Driftwood's analysts do that reading and turn thousands of pages into a one-page thesis. Reputation is the whole franchise. A single confidently wrong claim in a report damages the business.

The problem

Every analyst spends roughly half of every week on source-document intake. They open SEC filings, scan for the sections they care about (risk factors, MD&A, business segments), copy-paste passages, and compare year over year. Only after that intake work can they produce any original analysis.

The intake work is boring, necessary, and repetitive across analysts. Multiple analysts read the same Apple 10-K every January, each in their own local files. Hiring more analysts does not fix it, because the bottleneck scales linearly with coverage. Driftwood wants to fix the bottleneck itself.

What they want

The ask is an internal chatbot, Document Copilot, where any Driftwood analyst can:

• Ask questions in plain English about any filing in Driftwood's curated corpus
• Get a sourced answer that cites the specific filing and the specific page
• Trust the answer enough to base downstream analysis on it
• Use it from a browser, logged in with their Driftwood email address
• See their own past conversations

The last two points matter more than they look. This is a deployed browser application with real authentication and saved history, not a notebook demo. Building that end to end (backend, frontend, database, auth, deployment) is exactly what this tutorial covers.

Why not ChatGPT or Copilot

In the video Dave gives the two reasons a firm like this cannot just use an off-the-shelf assistant, the same two that come up with real clients of any reasonable size.

First, privacy, compliance, and security. Most companies simply cannot let employees paste internal work into consumer ChatGPT. Data handling has to be strict about what gets stored where and what gets shared with whom. You still need a language model, so the LLM endpoint is the one thing that gets whitelisted, typically through an enterprise offering such as AWS Bedrock or Microsoft Azure with explicit data policies. That is usually the only way an application like this gets approved in an enterprise environment.

Second, customization and standardization. Off-the-shelf tools are generic. If you dump these filings into ChatGPT and let five analysts ask questions, they will get five different answers within minutes, because everyone uses the tool a little differently and large corpora quickly exceed what a context window handles well. A firm of 40 analysts needs one standardized tool with custom behavior on top of the model, or the output stays generic and inconsistent.

The trust contract

This is a research firm. Their entire business is being right, so the bot must:

• Never invent facts. If the answer is not in the corpus, it says so.
• Always cite. Every claim links to the source filing and page.
• Show the underlying passage so the analyst can verify in one click.

A wrong but confident answer is worse than no answer. As Dave puts it in the video, a hallucinated fact becomes faulty input to faulty analysis, and for a firm like Driftwood that is a very costly mistake. The tool accelerates the heavy lifting, but the analyst remains responsible for fact-checking the output, and the product has to make that fact-checking a one-click action.

This contract shapes the entire design, not just a line in a prompt. It drives the retrieval strategy, the typed agent output, a dedicated grounding validator that fails closed, and a citation UI that surfaces the exact source passage. You will see it recur in nearly every later stage.

An example analyst question

The brief in docs/client-brief.md lists ten example questions the bot should handle with cited answers. Here is the first one:

Across Apple's 2021-2025 10-Ks, how did the revenue mix between iPhone, Services, Mac, iPad, and Wearables change, and which category appears to have contributed most to any mix shift?

Answering that without AI means digging through five annual reports and reconciling segment tables by hand. That is the depth of question the system works toward. Note also question 10 in the brief. If an analyst asks whether the filings prove generative AI improved margins, the bot must refuse to infer beyond what the corpus supports. Knowing when to say "not enough evidence" is part of the product.

The corpus

The sample corpus is 10-K filings for five companies, downloaded from SEC EDGAR (public domain):

These are real, large, messy documents. Each runs hundreds of pages, full of narrative sections, financial tables, and legal language. That makes them a genuinely interesting retrieval problem rather than a toy dataset. You download them yourself in the setup stage.

Out of scope

The brief is explicit about what this project is not, which is just as important as what it is:

• No trading recommendations or stock picks
• No external data sources (no news, no social, no alternative data)
• Nothing generating analysis not grounded in the corpus
• No multi-tenant or multi-client setup (Driftwood-internal only)
• No billing, plans, or paywalls
• No mobile app

Definition of done

A pilot group of five senior analysts uses the deployed app for a week. If it saves each of them at least 3 hours per week, Driftwood rolls it out firm-wide. That is the target every stage of this build works toward. Not a demo, but a browser app a pilot group can actually work in.

Checkpoint

Before moving on, you should be able to answer:

• Who uses Document Copilot and what problem does it remove from their week?
• What are the three parts of the trust contract, and why is a confident wrong answer worse than no answer?
• Why is ChatGPT or Copilot not an acceptable answer for this client?
• What is in the corpus, and what is explicitly out of scope?

Next: Architecture and tooling

The monorepo setup, the locked stack, and the architecture doc you will keep coming back to.