Build a HIPAA-Aware AI Intake System

Scaffold a production-grade GitHub repo for a healthcare AI intake system.

Introduction

30 Second Summary

Every doctor's office has a front desk buried in intake paperwork. Patients fill out the same forms on clipboards, staff re-type the answers into a computer, and the doctor waits.

In this project, you will build the foundation for an AI-powered patient intake system by creating a production-quality GitHub repository, a standardized prompt library, architecture documentation, and a real pilot-outreach pitch for a San Antonio healthcare practice.

What You'll Build

A HIPAA-aware GitHub repository (clinic-intake-ai) that serves as the system foundation for an AI patient intake system targeting a 3-provider healthcare practice at under $100 per provider per month.

By the end of this project, you'll have:

  • A production-quality repo with an industry-standard folder layout, documented naming conventions, inline Mermaid diagrams, and a 7-block README that a senior engineer would recognize as professional-grade.
  • An Architecture Decision Record documenting why Amazon Web Services Bedrock under a Business Associate Agreement is the sole Large Language Model provider, with rejected alternatives and honest trade-offs.
  • A standardized prompt library of four reusable Claude templates with HIPAA-awareness guardrails baked in, version-controlled in the repo instead of lost in chat history.
  • A pilot-outreach package with a contacts list, a visual pitch deck designed in Claude Desktop, and a coffee-meeting pitch message sent to a real person the same day the repo goes live.
  • A two-page leave-behind pitch with a Mermaid-generated workflow visual, ready to hand off at a coffee meeting (Secret Mission).

Are there any prerequisites?

You should be familiar with Git basics (clone, add, commit, push). Understanding why healthcare data needs special handling is helpful but not required. This guide defines every term before using it.

Create the Repo with an Industry-Standard Naming Scheme

To build a HIPAA-aware intake system that a senior engineer would take seriously, the repo itself has to look production-grade from the first commit. That means every folder name, every file name, and every commit message follows a documented convention. In this step, you will create the clinic-intake-ai repo on GitHub, scaffold its folder structure using lowercase kebab-case naming, and commit a conventions file that locks in the rules for the entire project.

In This Step, Get Ready To:
  • Create the clinic-intake-ai GitHub repo with an MIT license and clone it locally.
  • Scaffold the folder structure using industry-standard kebab-case naming conventions.
  • Commit a CONVENTIONS.md file, a .gitignore, and the full folder scaffold as the first commit.
Create the GitHub Repo and Clone It Locally

The GitHub CLI lets you create a repo, add a license, and clone it in a single command. No clicking through the GitHub web interface.

  • Open PowerShell or Git Bash.
  • Run the following command to create the repo and clone it.
gh repo create clinic-intake-ai --public --clone --license mit
cd clinic-intake-ai

What does this command do?

  • gh repo create clinic-intake-ai creates a new GitHub repo named clinic-intake-ai.
  • --public makes the repo visible to anyone on GitHub.
  • --clone clones the repo to your local machine immediately after creation.
  • --license mit adds an MIT license file to the repo automatically.
  • cd clinic-intake-ai moves you into the new repo folder so all future commands run from inside it.

Why clinic-intake-ai instead of something like ai-value-driven-systems-engineering?

The repo name says exactly what the system does in three words. Anyone scanning GitHub repos, whether a hiring manager, a collaborator, or a practice manager, immediately knows the domain and function. Abstract methodology names do not tell anyone what the project actually builds.

Seeing 'gh: command not found'?

The GitHub CLI may not be installed or may not be on your system PATH. Install it with winget install --id GitHub.cli, then close and reopen your terminal window. The PATH update only takes effect in a new terminal session. Help me troubleshoot my GitHub CLI installation.

Create the Folder Structure Using Industry-Standard Naming

Every folder in this project uses lowercase kebab-case: words separated by hyphens, no underscores, no camelCase. This follows the Google developer style guide and the most common pattern across major open-source projects like jQuery, Node.js, Express, and React.

  • Run the following commands to create the folder structure.
mkdir docs\adr
mkdir docs\diagrams
mkdir docs\prompts
mkdir pilot-outreach
mkdir scripts

What is each folder for?

  • docs/ holds all documentation. This is the most common name in open source.
  • docs/adr/ holds Architecture Decision Records. Files follow the pattern 0001-short-kebab-slug.md.
  • docs/diagrams/ holds Mermaid diagram files, named descriptively: system-flowchart.md, data-flow-sequence.md.
  • docs/prompts/ holds standardized Claude prompt templates, named by purpose: workflow-diagram.md, outreach-message.md.
  • pilot-outreach/ holds all outreach artifacts: contacts, pitch logs, and pitch decks.
  • scripts/ holds operational scripts named by function: spinup.sh, teardown.sh, cost-check.sh.

Why kebab-case instead of underscores or camelCase?

Hyphens are preferred over underscores because search engines interpret hyphens as word separators. The Google developer style guide recommends lowercase with hyphens for file and folder names. This is the same convention used by the most popular open-source projects.

Create the .gitignore, CONVENTIONS.md, and Initial Commit

Git tracks every file in the repo by default. A .gitignore file tells Git which files to ignore, keeping sensitive files like .env and generated clutter out of version control. A CONVENTIONS.md file documents every naming rule, commit standard, and guardrail so anyone reading the repo knows the rules without guessing.

  • Create a file called .gitignore in the repo root with the following content.
# Environment and secrets
.env

# Dependencies
node_modules/

# OS files
.DS_Store
Thumbs.db

# Editor files
.vscode/

# Python cache
__pycache__/

# Logs and temp files
*.log
*.tmp
  • Create a file called CONVENTIONS.md in the repo root with the following content.
# Conventions

This file documents every naming rule, commit standard, and guardrail for the clinic-intake-ai project.

## Naming

- **Folders and files**: lowercase kebab-case (words separated by hyphens). No underscores, no camelCase.
- **Architecture Decision Record files**: zero-padded sequential number + verb-first kebab-case slug. Example: `0001-use-bedrock-under-baa.md`.
- **Prompt templates**: kebab-case, named by purpose. Example: `workflow-diagram.md`.
- **Constants and environment variables**: UPPER_SNAKE_CASE. Example: `AWS_REGION`.

## Commits

All commits follow the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) standard.

Format: `<type>(<optional scope>): <description>`

Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci`

Examples:
- `chore: scaffold repo with folder structure`
- `docs(adr): add ADR 0001 selecting Bedrock under BAA`
- `feat(intake): add form validation`

## Diagrams

- All diagrams use Mermaid syntax embedded in Markdown files.
- Mermaid renders natively on GitHub with no install required.
- Use abbreviations inside Mermaid node labels for readability. Define each abbreviation in a legend comment above the diagram.

## Prompt Templates

- All prompt templates live in `docs/prompts/`.
- Every template includes HIPAA-awareness guardrails:
  - Never include real patient data.
  - Always use synthetic examples.
  - Always spell out acronyms on first use.
  - Always maintain 7th-grade reading level.

## AI Assistance

- Claude Desktop (Claude Max) is used for drafting documentation, generating diagrams via prompt templates, designing visual artifacts, and maintaining solo-operator voice consistency.
- All AI-generated artifacts are reviewed and edited by a human before committing.

What are Conventional Commits?

Conventional Commits is a standard format for commit messages. Every commit starts with a type like docs, feat, or chore, followed by a colon and a short description. This makes the commit history scannable at a glance. Anyone running git log --oneline can immediately see what each commit changed and why.

Now that both files are created, it is time to stage everything and make the first commit.

  • Stage all files and commit using the Conventional Commits format.
git add .
git commit -m "chore: scaffold repo with folder structure, LICENSE, conventions, and .gitignore"
git push origin main

What does this command do?

  • git add . stages every new and changed file in the repo.
  • git commit -m "..." creates a commit with the message in quotes. The chore: prefix tells anyone reading the history that this commit is a maintenance task, not a new feature or a bug fix.
  • git push origin main pushes your local commit to the main branch on GitHub so the repo is live.

Seeing 'error: src refspec main does not match any'?

This usually means your default branch is named master instead of main. Run git branch to check your branch name, then push to whichever branch is listed. Help me fix my branch name issue.

Open your repo on GitHub in a browser to verify the push worked. You should see the LICENSE, .gitignore, CONVENTIONS.md, and the docs/, pilot-outreach/, and scripts/ folders listed in the file tree.

What should I see?

GitHub may not show empty folders. If you do not see docs/adr/ or scripts/ in the file tree, that is normal. Git does not track empty directories. These folders will appear once you add files to them in later steps.

Your repo is live with a documented structure and a clean first commit. Next up, you will build a library of standardized Claude prompt templates that enforce consistent, HIPAA-aware output for every artifact in the project.

Create the Standardized Prompt Library

Your repo has a clean folder structure and documented conventions. Now you need to fill docs/prompts/ with reusable Claude prompt templates that enforce consistent output for every artifact in the project.

Every prompt you write today will include HIPAA-awareness guardrails so no one accidentally pastes real patient data into Claude or generates output that sounds like enterprise jargon. These prompts are version-controlled artifacts. They live in the repo, not in someone's chat history.

In This Step, Get Ready To:
  • Create four standardized prompt templates covering workflow diagrams, topology diagrams, Architecture Decision Records, and outreach messages.
  • Bake HIPAA-awareness guardrails into every template so future artifacts follow the same security rules automatically.
  • Commit the entire prompt library to version control as a single, traceable unit.
Create the Workflow Diagram Prompt Template

Each prompt template follows the same three-section structure: Purpose, Guardrails, and Prompt. The Purpose section tells you when to use the template. The Guardrails section lists the safety rules. The Prompt section gives you a copy-and-paste block with bracketed placeholders you fill in before sending to Claude.

  • Create a new file at docs/prompts/workflow-diagram.md.
  • Add a Purpose section explaining that this template generates a Mermaid flowchart showing how a process moves through the intake system.
  • Add a Guardrails section with these rules: never use real patient data, use synthetic examples only, spell out all acronyms on first use in surrounding text, use short abbreviations (API, LLM, BAA) inside Mermaid node labels for readability, and add a legend comment above the diagram defining each abbreviation.
  • Add a Prompt section with a copy-and-paste template. Include bracketed placeholders the user fills in. Include system context: HIPAA-aware intake system, Amazon Web Services Bedrock under Business Associate Agreement, $100/provider/month ceiling, synthetic data only. Include output requirements: flowchart orientation, subgraphs, placeholder labels, Mermaid-only output.

Here is an example of what your workflow diagram prompt template could look like:

# Workflow Diagram Prompt Template

## Purpose

Generate a Mermaid flowchart showing how a process moves through the
Health Insurance Portability and Accountability Act (HIPAA)-aware
patient intake system.

## Guardrails

- Never use real patient data. Use synthetic examples only.
- Spell out all acronyms on first use in surrounding text.
- Inside Mermaid node labels, use short abbreviations (API, LLM, BAA)
  for readability.
- Add a legend comment above the diagram defining each abbreviation.
- Maintain 7th-grade reading level in all surrounding text.

## Prompt

Copy the block below, fill in the bracketed placeholders, and paste
into Claude Desktop.

```
You are a systems architect documenting a HIPAA-aware patient intake
system. The system uses Amazon Web Services (AWS) Bedrock under a
Business Associate Agreement (BAA) as the sole Large Language Model
(LLM) provider. The cost ceiling is $100 per provider per month.
All data in examples must be synthetic.

Generate a Mermaid flowchart for the following process:

- Process name: [PROCESS NAME]
- Starting actor: [WHO OR WHAT TRIGGERS THE PROCESS]
- Steps: [LIST THE STEPS IN ORDER]
- End state: [WHAT THE FINAL OUTPUT OR CONFIRMATION LOOKS LIKE]

Requirements:
- Use flowchart TD (top-down) orientation.
- Group related steps into subgraphs with descriptive names.
- Use short labels inside nodes (abbreviations OK).
- Output only the Mermaid code block. No surrounding explanation.
```

Why version-control prompts instead of keeping them in chat history?

Chat history is ephemeral. If you close the conversation or hit a session limit, the prompt is gone. When prompts live in docs/prompts/, anyone on the project can reproduce the same output months later. You can also diff changes to prompts over time, just like code.

Create the Topology Diagram and Architecture Decision Record Prompt Templates

The topology diagram template serves a different purpose than the workflow template. Instead of showing how a process flows, it shows what components exist, how they connect, and where the HIPAA boundary falls.

  • Create docs/prompts/topology-diagram.md using the same three-section structure (Purpose, Guardrails, Prompt).
  • Set the Purpose to: generate a system topology showing what components exist, how they connect, and where the HIPAA boundary falls.
  • Add topology-specific guardrails: always show the HIPAA-eligible services boundary and the Business Associate Agreement coverage boundary clearly. Label external actors outside the system boundary.
  • Add a prompt template with bracketed placeholders for component names, connection types, and boundary labels.

Next, create the Architecture Decision Record template. An Architecture Decision Record (ADR) captures one decision, why you made it, and what you rejected. The prompt template ensures every ADR follows the Markdown Architectural Decision Records (MADR) format consistently.

  • Create docs/prompts/architecture-decision-record.md using the same three-section structure.
  • Set the Purpose to: generate an Architecture Decision Record in the MADR format.
  • Add ADR-specific guardrails: spell out every acronym, write at 7th-grade reading level, be honest about trade-offs, always include a "do nothing / status quo" alternative if relevant, and never claim HIPAA compliance.
  • Add a prompt template with bracketed placeholders for the decision title, context, decision drivers, alternatives, and consequences.

Why "never claim HIPAA compliance" in the guardrails?

HIPAA compliance requires a signed Business Associate Agreement, configured encryption, access controls, audit logging, and more. No GitHub repo alone makes you compliant. Claiming compliance prematurely would be misleading. The guardrail keeps your documentation honest by stating what IS in place and what IS NOT.

Create the Outreach Message Prompt Template and Commit the Library

The outreach message template is different from the other three. It generates text for a practice manager, not an engineer. The guardrails flip: instead of requiring technical precision, they ban technical language entirely.

  • Create docs/prompts/outreach-message.md using the same three-section structure.
  • Set the Purpose to: generate a casual outreach message to a practice manager.
  • Add outreach-specific guardrails: never mention HIPAA, AI, machine learning, or technical terms in the first message. Never sound like a sales pitch. Keep under 100 words. Write as a real person, not a company.
  • Add a prompt template with bracketed placeholders for the contact's role, how you know them, and what you want to learn from the meeting.

You now have all four prompt templates. Time to commit the entire library as a single unit.

  • Stage and commit the prompt library.
git add docs/prompts/
git commit -m "docs(prompts): add standardized prompt templates for diagrams, Architecture Decision Records, and outreach"
git push origin main

What does this commit message do?

This commit follows the Conventional Commits standard you documented in CONVENTIONS.md. The type is docs because you are adding documentation. The scope (prompts) narrows it to the prompt library. The description says exactly what changed.

Getting a "nothing to commit" error?

Make sure your four files are saved inside docs/prompts/ and not in the repo root. Run dir docs\prompts (PowerShell) or ls docs/prompts (Git Bash) to verify all four files appear. If they do not, move them to the correct folder and try the commit again. Help me troubleshoot my git commit.

Your prompt library is committed and pushed. Every future diagram, Architecture Decision Record, and outreach message will start from these templates instead of a blank chat window. Next up, you will use these templates to draft the 7-block README with inline Mermaid diagrams.

Write the 7-Block README with Mermaid Diagrams

Your prompt library is committed and ready to use. Now you need a README that does more than describe the project. It needs to discipline it.

A good README sets boundaries. It declares the cost ceiling, the HIPAA posture, and the pilot-outreach status so every future iteration has to fit within what this document promises. This README also includes inline Mermaid diagrams that render directly on GitHub. Anyone landing on the repo sees the system topology and data flow at a glance, with zero extra tools required.

In This Step, Get Ready To:
  • Use your prompt templates in Claude Desktop to generate two Mermaid diagrams for the README.
  • Assemble a 7-block README that covers the sell, data handling, cost ceiling, HIPAA posture, outreach status, architecture, and next steps.
  • Commit the README with inline Mermaid diagrams that render automatically on GitHub.
Draft the README Using Claude Desktop and the Prompt Templates

The prompt templates you committed in Step 2 are not just documentation. They are copy-paste tools. You will use two of them right now to generate the Mermaid diagrams that go inside the README.

  • Open Claude Desktop.
  • Open docs/prompts/workflow-diagram.md in a text editor and copy the prompt template.
  • Paste it into Claude Desktop and fill in the bracketed placeholders to describe the patient intake data flow: a patient fills out an intake form, it submits to an API Gateway, the gateway sends raw text to Bedrock, Bedrock returns structured data, the gateway stores the record, and the patient sees a confirmation.
  • Copy the Mermaid output Claude generates. You will paste this into the README shortly.
  • Now open docs/prompts/topology-diagram.md and copy that prompt template.
  • Paste it into Claude Desktop and fill in the placeholders. Include these components: Patient, Practice Manager, Web Intake Form, API Gateway, Amazon Bedrock (LLM under BAA), Database (encrypted at rest), and S3 Document Storage.
  • Copy the topology Mermaid output as well.

How do Mermaid diagrams render on GitHub?

Mermaid renders natively on GitHub inside fenced code blocks. You wrap your diagram code in triple backticks with mermaid as the language identifier. GitHub turns the text into a visual diagram automatically. No plugins, no image exports, no extra tools.

Now prompt Claude to assemble the full README. Give Claude both Mermaid outputs and ask it to build a README.md with exactly seven blocks:

  • Block 1: 20-Second Sell. One paragraph covering what this system does, for whom, and the cost ceiling. Spell out Health Insurance Portability and Accountability Act (HIPAA) on first use.
  • Block 2: Data Handling. How patient data flows. Define Protected Health Information (PHI) in one sentence. Include the inline Mermaid data-flow diagram. State that no PHI lives in the repo.
  • Block 3: Cost Ceiling. Hard cap of $100/provider/month. Break down where costs go. State that any iteration exceeding this ceiling gets rejected.
  • Block 4: HIPAA Posture. Current status: not HIPAA-compliant yet. List what is in place and what is not. Define Business Associate Agreement (BAA) in one sentence.
  • Block 5: Pilot-Outreach Status. Link to pilot-outreach/contacts.md. State the goal: one signed letter of intent before code handles real patient data.
  • Block 6: Architecture Placeholder. Include the Mermaid topology flowchart. Mark it as a placeholder.
  • Block 7: Next-Iteration Pointer. What iteration 2 will build.

Tell Claude to use plain English at a 7th-grade reading level with a solo-operator small-and-medium business tone. Every acronym must be spelled out on first use, then abbreviated in parentheses.

Why spell out acronyms if the audience is technical?

The audience is not only technical. A practice manager, a hiring manager, or a potential collaborator might read this README. Spelling out acronyms on first use (HIPAA, PHI, BAA, LLM, ADR, AWS, API) makes the document accessible to everyone who lands on the repo.

Pro tip: Mermaid abbreviations

Inside Mermaid node labels, use short abbreviations like API, LLM, and BAA to keep diagrams readable. Add a legend comment above the Mermaid block defining each abbreviation. The surrounding README text already spells out the full terms.

Review and Refine the Tone

Claude's first draft is a starting point, not a finished product. The README needs to sound like you wrote it, not like a consultant did.

  • Read the draft out loud. Rewrite anything that sounds like enterprise marketing copy.
  • Verify every acronym is defined on first use: HIPAA, PHI, BAA, LLM (Large Language Model), ADR (Architecture Decision Record), AWS (Amazon Web Services), API (Application Programming Interface).
  • Check that the HIPAA Posture block says "not HIPAA-compliant yet" and lists what is in place versus what is not.
  • Confirm the Cost Ceiling block states the hard cap of $100/provider/month and that any iteration exceeding it gets rejected.

Why state "not HIPAA-compliant yet"?

No HIPAA certification exists for cloud providers. HIPAA compliance requires a signed Business Associate Agreement, configured encryption, access controls, audit logging, and more. Claiming compliance prematurely would be misleading. The README is honest about where the project stands right now.

Preview the Mermaid diagrams to make sure they render correctly. You have two options:

  • Paste the Mermaid code into the Mermaid Live Editor for instant preview.
  • Push to GitHub and view the README in your browser. GitHub renders Mermaid natively.

Mermaid diagram not rendering?

Check that your fenced code block uses mermaid (lowercase) as the language identifier. Also watch out for the word end in lowercase as a node label. It conflicts with Mermaid's subgraph closing keyword. Capitalize it or wrap it in quotes.

Still stuck? Help me debug my Mermaid diagram.

Save and Commit the README

Your README is reviewed, your diagrams render, and every acronym is defined. Time to commit.

  • Save the final README.md to the root of your clinic-intake-ai repo.
  • Stage, commit, and push using the Conventional Commits format:
git add README.md
git commit -m "docs: add 7-block README with cost ceiling, HIPAA posture, and Mermaid diagrams"
git push origin main

What does this commit message mean?

The docs: prefix follows the Conventional Commits standard. It signals that this commit changes documentation, not application code. The description after the colon summarizes what was added. This format makes your commit history scannable and machine-readable.

Your README is live. Anyone visiting the repo now sees the system topology, the cost ceiling, and the HIPAA posture in one scroll. Next up, you will write Architecture Decision Record 0001 to lock in the most important early decision: which AI service to use for a system that handles patient data.

Write Architecture Decision Record 0001

Your README promises that Amazon Web Services Bedrock under a Business Associate Agreement is the AI provider for this system. But promises without documentation get relitigated every time a new person joins or a shiny alternative appears. An Architecture Decision Record locks in that choice by capturing what you decided, why, and what you rejected. Once accepted, an Architecture Decision Record is never reopened. If the decision changes later, you supersede it with a new one.

Architecture Decision Record 0001 does not configure Bedrock or write any code. It documents the reasoning so future iterations do not waste time re-debating "should we use OpenAI or Bedrock or self-host?" That debate is settled here.

In This Step, Get Ready To:
  • Draft Architecture Decision Record 0001 using your prompt template and Claude Desktop.
  • Document rejected alternatives with honest trade-offs.
  • Commit the Architecture Decision Record following the zero-padded kebab-case naming convention.
Draft Architecture Decision Record 0001 Using the Prompt Template

Your prompt library already has a template for Architecture Decision Records in the Markdown Architectural Decision Records (MADR) format. MADR extends the original Architecture Decision Record template with two critical sections: Decision Drivers and Alternatives Considered. The Alternatives Considered section is what prevents future relitigating.

  • Open Claude Desktop.
  • Open your Architecture Decision Record prompt template at docs/prompts/architecture-decision-record.md and copy its contents into Claude.
  • Fill in the bracketed placeholders with the following details.

The Decision section should state:

"Use Amazon Bedrock under a Business Associate Agreement as the sole Large Language Model provider."

The Decision Drivers section should list the constraints that shaped this choice:

  • Must support a Business Associate Agreement for Protected Health Information (PHI).
  • Solo operator with no dedicated DevOps team.
  • Hard cost ceiling of $100 per provider per month.
  • Existing Amazon Web Services knowledge and account.

The Alternatives Considered section should evaluate three rejected options:

  • OpenAI Application Programming Interface (API). No Business Associate Agreement available for standard API access. This is a hard disqualifier for any system handling Protected Health Information. Rejected.
  • Self-hosted open-source Large Language Model on Amazon Elastic Compute Cloud (EC2). The operational burden is too high for a solo operator. Total cost would exceed the $100 per provider per month ceiling. Rejected.
  • Google Cloud Vertex AI. Offers a Business Associate Agreement, but switching clouds adds learning overhead and operational complexity without delivering value for the target market. Rejected.

Tell Claude to include these key facts in the Context section:

  • Bedrock is on the Amazon Web Services HIPAA Eligible Services list, last updated April 13, 2026.
  • Bedrock does not store or log prompts and completions. It does not use customer data to train models.
  • Amazon Web Services offers a self-service Business Associate Addendum that customers can accept for all accounts in their organization.
  • No HIPAA certification exists for cloud providers. Amazon Web Services aligns with FedRAMP and NIST 800-53.

What Is a Business Associate Agreement?

A Business Associate Agreement (BAA) is a legal contract between a healthcare provider and any vendor that handles patient data on their behalf. Without a signed BAA, a vendor cannot legally touch Protected Health Information. Amazon Web Services offers a standardized BAA through a self-service process, which is what makes Bedrock viable for this system.

Why Bedrock Instead of OpenAI or Self-Hosting?

OpenAI's standard API does not offer a Business Associate Agreement, which immediately disqualifies it for Protected Health Information. Self-hosting an open-source model on EC2 gives you full control, but the operational burden and cost exceed what a solo operator can sustain at $100 per provider per month.

Bedrock is a managed service. Amazon Web Services handles the infrastructure, the BAA covers the data handling, and prompts are not stored or used for training. For a solo operator building a healthcare system, that combination is the only one that fits all the constraints.

Review the output Claude generates. The Architecture Decision Record should have these sections in order: Title, Status (accepted), Date, Context, Decision, Decision Drivers, Alternatives Considered (with pros, cons, and reason for rejection), and Consequences (both positive and negative).

Pro tip: be honest about trade-offs

The Consequences section should include negative consequences too. For example, Bedrock locks you into the Amazon Web Services ecosystem, and model selection is more limited than OpenAI's catalog. A good Architecture Decision Record does not pretend the chosen option is perfect. It shows you understood the trade-offs and chose deliberately.

Save and Commit Architecture Decision Record 0001

Architecture Decision Record files follow a specific naming convention: a zero-padded sequential number followed by a verb-first slug in kebab-case. Zero-padding ensures files sort correctly up to 9999. The verb-first slug makes the decision action immediately clear from the filename.

  • Save the Claude output as docs/adr/0001-use-bedrock-under-baa.md in your repo.
  • Stage and commit the file.
git add docs\adr\0001-use-bedrock-under-baa.md
git commit -m "docs(adr): add Architecture Decision Record 0001 selecting Bedrock under Business Associate Agreement"
git push origin main

What does this commit message do?

This follows the Conventional Commits standard. The type is docs because you are adding documentation, not a feature. The scope (adr) tells anyone reading the log exactly which part of the docs changed. The description spells out the decision so the commit history reads like a project timeline.

  • Verify the file is on GitHub by opening your clinic-intake-ai repo in a browser and navigating to docs/adr/.

What Should I See?

You should see 0001-use-bedrock-under-baa.md inside the docs/adr/ folder. Clicking the file should render the Markdown with all sections visible: Title, Status, Date, Context, Decision, Decision Drivers, Alternatives Considered, and Consequences.

File Not Showing Up on GitHub?

Make sure you ran all three commands: git add, git commit, and git push. Run git status to check if the file is still staged or untracked. If you see it listed, commit and push again. Help me troubleshoot my git push.

Your first Architecture Decision Record is committed. The Bedrock-under-BAA decision is now documented, defended, and permanent. Next up, you will bring the system to life visually with Mermaid diagrams and create the operations script stubs that hold the structure for future iterations.

Create the Mermaid Diagrams and Operations Script Stubs

Your Architecture Decision Record locked in the Bedrock decision. Now you need visuals that show how the system fits together. In this step, you will use your prompt templates to generate two Mermaid diagrams and create stub operations scripts that hold the structure for future iterations.

Mermaid diagrams are plain text inside Markdown files. They diff cleanly in Git, show up in pull request reviews, and render automatically on GitHub with no install required.

In This Step, Get Ready To:
  • Generate a system topology flowchart showing all components and the HIPAA boundary.
  • Generate a data-flow sequence diagram showing how a patient intake moves through the system.
  • Create three stub operations scripts that hold the structure for future iterations.
Create the System Topology Flowchart

The system topology flowchart shows what components exist, how they connect, and where the HIPAA boundary falls. Anyone landing on the repo can see the architecture at a glance.

  • Open Claude Desktop.
  • Open your topology diagram prompt template at docs/prompts/topology-diagram.md and copy the prompt into Claude.
  • Fill in the bracketed placeholders with these components: Patient, Practice Manager, Web Intake Form, API Gateway, Amazon Bedrock (LLM under BAA), Database (encrypted at rest), S3 Document Storage.
  • Make sure the diagram clearly shows the HIPAA-eligible services boundary and the Business Associate Agreement (BAA) coverage boundary.
  • Label external actors (Patient, Practice Manager) outside the system boundary.

Claude will generate a Mermaid flowchart block. The output will look something like this:

# System Topology

> PLACEHOLDER: This diagram represents the target architecture.
> Components will be implemented in future iterations.

<!-- Abbreviation Legend:
  API  = Application Programming Interface
  LLM  = Large Language Model
  BAA  = Business Associate Agreement
  S3   = Simple Storage Service
-->

```mermaid
flowchart TD
    P[Patient] --> WIF[Web Intake Form]
    PM[Practice Manager] --> WIF

    subgraph HIPAA-Eligible Services
        WIF --> APIGW[API Gateway]
        APIGW --> BRK[Amazon Bedrock\nLLM under BAA]
        APIGW --> DB[(Database\nEncrypted at Rest)]
        APIGW --> S3[S3 Document Storage]
        BRK --> APIGW
    end
```

What is a Mermaid flowchart?

A Mermaid flowchart is a text-based diagram that GitHub renders as a visual graphic. The flowchart TD line tells Mermaid to draw a top-down chart. Nodes are defined with labels in brackets like A[Label], and arrows like A --> B connect them. The subgraph keyword groups related components inside a labeled boundary.

Pro tip: abbreviations inside diagrams

Inside Mermaid node labels, use short abbreviations (API, LLM, BAA) to keep diagrams readable. The abbreviation legend comment above the diagram and the README define the full terms. This keeps node boxes compact while maintaining clarity.

  • Review Claude's output and adjust the node labels or layout if needed.
  • Add a PLACEHOLDER note at the top of the file indicating this is the target architecture.
  • Add an abbreviation legend comment above the Mermaid block defining each short form.
  • Save the file as docs/diagrams/system-flowchart.md.

Mermaid diagram not rendering?

Avoid using the word "end" in lowercase as a node label. It conflicts with the subgraph closing keyword. Capitalize it or wrap it in quotes instead. You can preview your diagram at https://mermaid.live before committing. Help me debug my Mermaid diagram.

Create the Data-Flow Sequence Diagram

The topology flowchart shows what exists. The sequence diagram shows what happens when a patient actually uses the system. It traces a single intake from start to finish.

  • Open your workflow diagram prompt template at docs/prompts/workflow-diagram.md and copy the prompt into Claude Desktop.
  • Describe this workflow in the bracketed placeholders: a patient fills out an intake form, it submits to the API Gateway, the gateway sends raw text to Bedrock, Bedrock returns structured data, the gateway stores the record, and the patient sees a confirmation.

Claude will generate a Mermaid sequenceDiagram block. The output will look something like this:

# Data-Flow Sequence: Patient Intake

> PLACEHOLDER: This sequence represents the target data flow.
> Implementation happens in future iterations.

<!-- Abbreviation Legend:
  API  = Application Programming Interface
  LLM  = Large Language Model
  BAA  = Business Associate Agreement
-->

```mermaid
sequenceDiagram
    participant Patient
    participant Form as Web Intake Form
    participant APIGW as API Gateway
    participant BRK as Bedrock (LLM)
    participant DB as Database

    Patient->>Form: Fill out intake
    Form->>APIGW: Submit raw text
    APIGW->>BRK: Send text for structuring
    BRK-->>APIGW: Return structured data
    APIGW->>DB: Store record (encrypted)
    APIGW-->>Patient: Show confirmation
```

What is a sequence diagram?

A sequence diagram shows messages passing between participants over time, reading top to bottom. Solid arrows (->>) represent requests. Dashed arrows (-->>) represent responses. Each participant line declares a column in the diagram.

  • Review Claude's output and verify the flow matches the workflow described above.
  • Add a PLACEHOLDER note and abbreviation legend at the top of the file.
  • Save the file as docs/diagrams/data-flow-sequence.md.
Create Stub Operations Scripts and Commit Everything

Operations scripts automate the boring stuff: spinning up infrastructure, tearing it down, and checking costs. The scripts do not do anything yet. They are stubs that hold the structure so future iterations have a clear place to add real logic.

  • Create scripts/spinup.sh with the following content:
#!/bin/bash
# spinup.sh - Provisions infrastructure for clinic-intake-ai
# PLACEHOLDER: Real provisioning logic added in future iterations.

echo "spinup.sh is a placeholder. No resources provisioned yet."
  • Create scripts/teardown.sh with the following content:
#!/bin/bash
# teardown.sh - Destroys infrastructure for clinic-intake-ai
# PLACEHOLDER: Real teardown logic added in future iterations.

echo "teardown.sh is a placeholder. No resources to tear down yet."
  • Create scripts/cost-check.sh with the following content:
#!/bin/bash
# cost-check.sh - Reports current AWS costs for clinic-intake-ai
# PLACEHOLDER: Real cost-checking logic added in future iterations.
# Target ceiling: $100/provider/month

echo "cost-check.sh is a placeholder. No costs to report yet."

Why are these .sh files on Windows?

Git Bash is bundled with Git for Windows and runs .sh files natively. These scripts stay as .sh because the deployment target is Linux-based AWS infrastructure. Keeping them as shell scripts now avoids a rewrite later.

  • Stage the diagrams and scripts, then commit and push.
git add docs/diagrams/ scripts/
git commit -m "chore: add Mermaid architecture diagrams and stub operations scripts"
git push origin main

What does this commit message mean?

The chore type in Conventional Commits is for maintenance tasks that do not add a feature or fix a bug. Adding placeholder diagrams and stub scripts falls into this category.

Your repo now has visual architecture documentation and a clear home for operations automation. Next up, you will build the pilot-outreach list and design a pitch deck that turns this technical foundation into a real conversation with a practice manager.

Build the Pilot-Outreach List and Design the Pitch Deck

Every file you have committed so far serves the same customer: a practice manager who has never heard of Amazon Web Services or Architecture Decision Records. This step is where the project stops looking like a homework assignment and starts looking like a business.

You will commit real warm contacts to version control, build a tracking structure for accountability, and design a visual pitch deck using Claude Desktop's design feature. The pitch deck is something you can actually hand to someone at a coffee meeting.

In This Step, Get Ready To:
  • Create a contacts list with 3 to 5 initials-only warm contacts and a pitch-tracking log.
  • Design a one-page visual pitch deck using Claude Desktop's design feature.
  • Commit all outreach artifacts to the repo.
Create the Contacts List and Pitch-Tracking Log

Pilot conversations take 2 to 3 months. The repo takes about 6 weeks. If outreach starts at the end, the system has no customer when it ships. The contacts list ships now so customer development runs in parallel with technical development.

Your repo is public, so privacy matters here. Use initials only. Never put full names, practice names, phone numbers, or email addresses in a public repo. Keep a private companion document on your local machine with full contact details, and make sure it is covered by your .gitignore.

  • Create pilot-outreach/contacts.md in your text editor.
  • Add 3 to 5 rows, one per warm contact. Each row should include the contact's initials, their role, specialty, approximate provider count, how you know them, and a status column set to "not contacted."

Here is an example of what a row looks like:

| Initials | Role             | Specialty       | Providers | Connection        | Status        |
|----------|------------------|-----------------|-----------|-------------------|---------------|
| J.R.     | Practice Manager | Family Medicine | 3         | Church group      | Not contacted |
| M.L.     | Office Admin     | Pediatrics      | 2         | Neighbor          | Not contacted |

Why initials only?

This repo is public on GitHub. Anyone can read it. Initials protect your contacts' privacy while still giving you a trackable, version-controlled list. Your private local document has the full details you need to actually reach out.

  • Create pilot-outreach/pitch-log.md to track every outreach attempt.
  • Add columns for date, contact initials, channel (text, email, in-person), a short summary of what you said, and the next step.
# Pitch Log

Track every outreach attempt here. One row per interaction.

| Date       | Initials | Channel   | Summary | Next Step |
|------------|----------|-----------|---------|-----------|
|            |          |           |         |           |

Why version-control outreach?

The pitch log is your accountability system. Every time you reach out to someone, you log it. Every time someone responds, you log it. This turns "I should talk to people" into a trackable pipeline with dates and next steps.

Design the One-Page Pitch Deck Using Claude Desktop's Design Feature

The pitch deck is for a practice manager, not an engineer. That means no technical terms. No mention of Amazon Web Services, Bedrock, Application Programming Interfaces, or Large Language Models. The entire page should be readable by someone who has never touched a computer beyond email.

  • Open Claude Desktop.
  • Use Claude's design feature to create a one-page visual pitch.
  • Ask Claude to design a single page with exactly four sections.

The four sections to include:

  • The Problem: Front desk staff spend too much time on intake paperwork.
  • The Solution: An AI assistant that handles intake before the patient arrives.
  • The Cost: Under $100 per provider per month. No long-term contract.
  • The Ask: Shadow the front desk for one morning to understand the current workflow.

Pro tip: keep it at 7th-grade level

Read your pitch out loud. If any sentence would confuse your grandmother, rewrite it. The goal is to sound like a helpful neighbor, not a technology vendor.

  • Review the design Claude generates. Ask Claude to revise anything that sounds too technical or too salesy.
  • Export or screenshot the final design and save it as pilot-outreach/pitch-deck.png.

Why no technical terms in the pitch?

Practice managers care about time saved, cost, and risk. They do not care which cloud provider you use or what an API is. Technical details belong in the repo. The pitch belongs in a conversation.

Commit the Outreach Files and Pitch Deck

All three outreach artifacts are ready. Time to commit them together so the outreach folder ships as a complete unit.

  • Open PowerShell or Git Bash and navigate to your clinic-intake-ai directory.
  • Stage and commit the outreach files.
git add pilot-outreach\
git commit -m "docs(outreach): add pilot contacts list, pitch log, and visual pitch deck"
git push origin main

What does this command do?

This stages everything in the pilot-outreach/ folder: your contacts list, pitch log, and pitch deck image. The commit message follows the Conventional Commits standard with docs as the type and outreach as the scope.

  • Verify the commit by running git log --oneline and confirming your outreach commit appears at the top.

What should I see?

Your most recent commit should show the message docs(outreach): add pilot contacts list, pitch log, and visual pitch deck at the top of the log. If you visit your GitHub repo in a browser, the pilot-outreach/ folder should now contain three files.

Your outreach pipeline is live. Next up, you will draft the actual coffee-meeting pitch message and run a final validation across the entire repo.

Draft the Coffee-Meeting Pitch and Final Validation

You have a production-quality repo with documented architecture, standardized prompts, Mermaid diagrams, and a visual pitch deck. Now it is time to use what you built. This step produces the actual message you send to a real person today and validates that every artifact in the repo meets the standards you documented in CONVENTIONS.md.

In This Step, Get Ready To:
  • Draft a coffee-meeting pitch message using the outreach prompt template from your prompt library.
  • Validate that all 18 expected files exist and every convention is followed.
  • Send the pitch to at least one warm contact and log the attempt in version control.
Draft the Coffee-Meeting Pitch Using the Outreach Prompt Template

The outreach message prompt template you created in Step 2 has guardrails baked in. It keeps the message under 100 words, avoids technical jargon, and sounds like a real person instead of a sales pitch. Now you put it to work with your actual contact details.

  • Open Claude Desktop.
  • Open your outreach message prompt template at docs/prompts/outreach-message.md and copy the full prompt.
  • Paste the prompt into Claude Desktop and fill in the bracketed placeholders with your real contact details and the initials of your first target contact.
  • Review the generated draft carefully.

Read the draft out loud. If any sentence sounds like it came from a marketing team, rewrite it. The message should sound like you are asking a friend for coffee, not pitching a product.

Pro tip: the no-jargon test

Your first message should never mention HIPAA, AI, machine learning, or any technical terms. If your practice manager contact has to Google a word in your message, it is the wrong word.

  • Save the final draft as pilot-outreach/pitch-draft.md.
Run the Final Repo Validation

Before the final commit, you need to confirm that every artifact is in place. The repo should contain 18 files across 6 directories, all following the naming conventions you documented.

  • Run the following command to list every file in the repo.
dir /s /b

Check the output against this list of 18 expected files:

  • Root: README.md, LICENSE, .gitignore, CONVENTIONS.md.
  • docs/adr/: 0001-use-bedrock-under-baa.md.
  • docs/diagrams/: system-flowchart.md, data-flow-sequence.md.
  • docs/prompts/: workflow-diagram.md, topology-diagram.md, architecture-decision-record.md, outreach-message.md.
  • scripts/: spinup.sh, teardown.sh, cost-check.sh.
  • pilot-outreach/: contacts.md, pitch-log.md, pitch-draft.md, pitch-deck.png.
  • Verify that all folder names are lowercase kebab-case. No underscores, no camelCase.
  • Open your repo in a browser on GitHub and verify that the Mermaid diagrams in README.md render as visual flowcharts.
  • Run the following command to verify all commits follow the Conventional Commits standard.
git log --oneline

What should I see?

Every commit message should start with a type prefix like chore:, docs:, or docs(outreach):. If any commit message does not follow the <type>(<optional scope>): <description> format, note it for future discipline. The convention is documented in your CONVENTIONS.md.

Commit, Send the Pitch, and Log It

This is the moment the project becomes real. You are committing the pitch draft, sending it to a warm contact, and logging the outreach attempt in version control.

  • Stage and commit the pitch draft along with any remaining files.
git add .
git commit -m "docs(outreach): add coffee-meeting pitch draft, repo scaffold complete"
git push origin main

What does this commit do?

This commit captures the pitch draft and any final files. The commit message uses the docs(outreach) scope to indicate it is an outreach documentation change. After this push, your GitHub repo is complete and publicly visible.

  • Send the pitch message to at least one warm contact from your pilot-outreach/contacts.md list today. Text, email, or direct message. Pick whichever channel feels most natural for that person.
  • Open pilot-outreach/pitch-log.md and add a new row with today's date, the contact's initials, the channel you used, a one-sentence summary, and the next step.
  • Commit the updated pitch log.
git add pilot-outreach\pitch-log.md
git commit -m "docs(outreach): log first outreach attempt"
git push origin main

Why log outreach in Git?

Version-controlling your outreach log creates an honest timeline. You can see exactly when you started customer conversations relative to when you started building. This is the discipline that separates a portfolio project from a real business foundation.

Initials only in public repos

Your repo is public. Never put full names, practice names, phone numbers, or email addresses in any committed file. Use initials only in contacts.md and pitch-log.md. Keep a private companion document with full details on your local machine. Make sure it is listed in your .gitignore.

Secret mission

Expand the Pitch Deck into a Two-Page Leave-Behind

Your one-page pitch deck gets you in the door. But what does the practice manager look at after you leave? A two-page leave-behind with a visual workflow gives them something to share with the other providers at the practice. This mission turns your pitch into a document that sells when you are not in the room.

Before you go

Clean Up Your Resources

This project runs entirely locally and on GitHub's free tier, so there are no ongoing cloud costs. Decide whether to keep your resources as they are, pause them to come back later, or delete them entirely.

Resources you used:

  • GitHub repository: clinic-intake-ai (public, free tier).
  • Local clone of the repository on your machine.
  • Claude Desktop conversation history used for drafting artifacts.
  • GitHub CLI authentication token (created during gh auth login).

Keep everything running

No action needed. Choose this if you are still actively building on the repo or planning to start iteration 2 soon.

  • Your GitHub repo stays public and accessible at no cost.
  • Your local clone stays on your machine, ready for the next commit.
  • Your Claude Desktop conversations persist in your chat history.

Pause - I'll come back to this later

Free up local disk space while keeping your remote repo intact on GitHub.

  • Confirm all changes are pushed by running git status and verifying a clean working tree.
  • Optionally delete the local clinic-intake-ai folder. You can re-clone it anytime with gh repo clone clinic-intake-ai.
  • Your GitHub repo remains live and free. No ongoing costs.

Delete - I don't want to use this again

Remove all project resources and start fresh.

  • Delete the GitHub repo by running gh repo delete clinic-intake-ai --yes in your terminal.
  • Delete the local clinic-intake-ai folder from your machine.
  • Optionally clear your Claude Desktop conversation history for this project.
  • Your GitHub CLI authentication remains active for future projects. To remove it, run gh auth logout.

Mission accomplished

That's a Wrap

Nice work! You just shipped a project that most engineers never build: one that starts with the customer, not the code. Your clinic-intake-ai repo looks like it was set up by a senior engineer, and you have a real pilot conversation in motion.

Here's what you accomplished:

  • Built a production-quality repo with an industry-standard folder layout, a standardized prompt library with HIPAA-awareness guardrails, and a CONVENTIONS.md that documents every naming rule, commit standard, and AI-assistance practice.
  • Wrote Architecture Decision Record 0001 documenting the Amazon Web Services Bedrock under Business Associate Agreement decision, with rejected alternatives and honest trade-offs that lock in the choice for all future iterations.
  • Created a 7-block README with inline Mermaid diagrams that render directly on GitHub, a real pilot-outreach list with warm contacts, and a coffee-meeting pitch that you sent to a real person today.
  • Expanded the pitch deck into a polished two-page leave-behind with a Mermaid-generated workflow visual, ready to hand off at a coffee meeting.

Ready to quiz yourself?