
## Context

I wanted the portfolio to do more than display information. I wanted it to answer for itself.

Not with a generic chatbot and not with a prompt that tries to improvise from thin air. The goal was narrower and more useful: let a visitor ask questions about my experience, projects, technical strengths, and background, and get answers grounded in the actual content already published on the site.

That design constraint shaped the entire implementation.

The assistant is not a toy layer on top of a marketing site. It is a retrieval system built around structured resume data, deterministic guardrails, and a thin production-safe proxy to GitHub Models.

## What I Built

The result is an AI assistant embedded directly into the portfolio experience that:

- loads a generated static resume dataset from the site itself  
- converts that content into searchable snippets  
- answers common questions locally when a deterministic path is safer and faster  
- ranks the most relevant context using embeddings and keyword fallback  
- folds recent conversation turns into retrieval so follow-up questions still make sense  
- keeps client-side embeddings fresh with cache versioning and TTL invalidation  
- calls GitHub Models through a Cloudflare Worker proxy  
- returns concise answers with citations tied to the underlying portfolio content  
- links cited projects, articles, and case studies back to their actual pages when possible  

In practical terms, visitors can ask questions like:

- What kind of backend systems has he built?
- Has he worked on payment infrastructure?
- What technologies does he use most often?
- What is his current role and background?

That sounds straightforward. The real work is in making the answers accurate, constrained, fast, and maintainable.

## The Core Design Decision

The most important decision was to treat the portfolio as a **data product**, not just a set of pages.

Because this site is statically exported, the assistant cannot rely on traditional server-side Next.js API routes. Instead, the content pipeline generates a static resume payload at build time and publishes it as a site asset.

That gave me a clean contract:

1. author content once in the portfolio  
2. normalize it into a structured resume payload  
3. let the assistant reason only over that approved dataset  

This is a much better engineering tradeoff than scraping rendered HTML or letting a model guess from partial page context.

## Abstract Architecture Diagram

```text
Visitor Question
      |
      v
Portfolio Assistant UI
      |
      +--> Load /api/resume.json
      |
      +--> Build normalized snippets
      |
      +--> Try local deterministic answer
      |
      +--> Retrieve relevant context
             | 
             +--> Embeddings available -> semantic ranking
             |
             +--> Otherwise -> keyword ranking fallback
      |
      v
Cloudflare Worker /assistant
      |
      +--> origin validation
      +--> payload validation
      +--> rate limiting
      +--> token isolation
      |
      v
GitHub Models
  - embeddings
  - chat completions
      |
      v
Structured JSON response + citations
      |
      v
Grounded answer rendered in the portfolio
```

## Request Lifecycle Diagram

The full request path is a little more interesting than the high-level diagram suggests, because there are several control points before the model is ever asked to answer.

```text
1. Visitor opens the footer assistant drawer
   |
   v
2. Client loads /api/resume.json
   |
   +--> generated at build time from content/about, content/home,
   |    content/settings, content/recommendations, and content/posts
   |
   v
3. Client normalizes content into snippets
   |
   +--> summary, about, skills, links, contact
   +--> experience and education entries
   +--> projects, articles, case studies, recommendations
   |
   v
4. Client computes a content hash
   |
   +--> used as the cache key for snippet embeddings
   +--> cache entries also carry a version and TTL so stale vectors can expire
   |
   v
5. Visitor submits a question
   |
   +--> local guardrails check scope and reject off-topic or adversarial prompts
   |
   +--> local deterministic answer path tries known patterns first
   |    - current role
   |    - education
   |    - common links
   |    - top technologies
   |    - payment-related experience
   |
   +--> if local answer exists, return immediately with citations
   |
   v
6. Retrieval phase builds the search intent
   |
   +--> combine current question with a small window of recent conversation
   +--> preserve who said what so follow-up turns keep their meaning
   |
   v
7. Retrieval phase selects supporting evidence
   |
   +--> embeddings ready
   |    - embed the conversation-aware retrieval query
   |    - score all snippets by cosine similarity
   |
   +--> embeddings unavailable
   |    - fall back to keyword overlap scoring
   |
   v
8. Top-ranked snippets only are sent to the model
   |
   +--> recent chat context is included
    +--> response is constrained to a JSON schema
    |
    v
9. Cloudflare Worker /assistant
   |
   +--> validate allowed origin
   +--> enforce POST + application/json
   +--> parse and validate request payload
   +--> apply per-IP rate limiting
   +--> keep GitHub Models token on the server boundary
   |
   v
10. GitHub Models
   |
   +--> embeddings endpoint for semantic retrieval
   +--> chat completions endpoint for grounded answer generation
   |
   v
11. Client validates model output
    |
    +--> parse JSON
    +--> enforce answer shape
    +--> discard invalid citation IDs
    +--> downgrade unsupported answers to "missing"
    +--> if the model path fails but retrieval is strong, show a closest-match fallback
    |
    v
12. UI renders final answer + snippet citations
```

## Why the Resume API Matters

The assistant is powered by a generated `resume.json` representation of the site content. That payload aggregates the information that actually matters to a recruiter, hiring manager, or engineering leader:

- summary and about information  
- experience history  
- education  
- links  
- projects  
- articles and case studies  
- recommendations and proof points  

That means the assistant is reasoning over normalized, intentional content rather than a noisy DOM.

From an architecture perspective, this matters for three reasons:

- **consistency**: the UI and the assistant share the same source of truth  
- **reliability**: the payload shape is stable and easy to evolve  
- **observability**: retrieval logic can work on well-defined content chunks instead of ambiguous page fragments  

## Embeddings and Retrieval Strategy

This is where the assistant becomes meaningfully useful.

I break the resume payload into small, semantically focused snippets. Each snippet represents a coherent unit such as:

- a role in my experience timeline  
- an education entry  
- a project or article  
- a recommendation  
- a skills or summary block  

Those snippets are then embedded through GitHub Models and ranked against the user’s question using vector similarity.

### Retrieval flow

- the client loads the resume data  
- it builds a snippet set and computes a hash of the content  
- snippet embeddings are cached locally by model and content hash  
- when a user asks a question, the question is embedded  
- the system selects the highest-signal snippets and sends only that context to the model  

This does two things well:

1. it improves answer quality because the model is given the most relevant evidence instead of the whole resume  
2. it keeps the design efficient by avoiding unnecessary repeated embedding work for unchanged content  

The hash-based cache boundary matters more than it may seem. It means embeddings are tied to the exact published content state. If the resume changes, the cache key changes too, so the assistant does not accidentally reuse vectors generated for older content.

I also added a keyword-based fallback path. If embeddings are unavailable for any reason, the assistant still works by ranking snippets through lexical overlap. That is an important operational detail: degraded mode is still useful mode.

There is now a second cache-safety layer as well: embeddings stored in the browser are namespaced by a cache version and expire after a TTL window. That matters when the content shape, ranking strategy, or embedding handling changes. A content hash prevents wrong reuse across resume changes, while versioning and TTL help retire older cached vectors after retrieval logic improves.

## Multi-Turn Retrieval, Not Just Multi-Turn UI

One subtle weakness in many portfolio assistants is that they only use chat history for display, not for retrieval.

I wanted follow-up questions to work more naturally.

So the assistant now uses a small window of recent conversation turns when building the retrieval query. That means questions like:

- What was his first project?
- What about his recent work?
- Did any of that involve payments?

can be interpreted in relation to the previous turns rather than as isolated fragments.

This does not mean the model gets free rein to improvise from conversation memory. The important detail is that retrieval itself becomes context-aware. The system still goes back to the published resume dataset, but it does so with a better understanding of what the visitor is referring to.

The conversation is also persisted locally in the browser, with message role information preserved, so both the UI and retrieval layer know which turns came from the visitor and which came from the assistant.

## Citations That Resolve Back to Real Content

Early citations were useful as proof, but they were still mostly internal identifiers.

I tightened that up so references to projects, posts, and case studies can carry real URLs. When the assistant cites one of those snippets, the UI can render a direct link back to the corresponding page on the portfolio.

That improves two things:

- the answer feels more inspectable because a visitor can immediately open the source material
- the assistant becomes a navigation surface, not just a response surface

That is an underrated product detail. In a portfolio, a good answer should often lead the visitor deeper into the work.

## Better Failure Handling When Retrieval Is Strong but Generation Fails

Another practical improvement was separating retrieval failure from generation failure.

Those are not the same problem.

If the model request fails because of a rate limit or temporary upstream issue, but retrieval already found a strong matching snippet, the assistant now has a more graceful degraded path. Instead of immediately saying the information is unavailable, it can return the closest relevant reference and make that uncertainty explicit.

The wording is intentionally careful. It does not pretend to be a full grounded answer if the full answer path did not complete. It says, in effect: here is the closest relevant source I could find.

That is a much more honest fallback than collapsing every upstream failure into "I don't know."

## A Safer Model Boundary with Cloudflare Workers

I did not want model credentials exposed in the browser, and I did not want the frontend talking directly to a third-party inference endpoint.

So I added a Cloudflare Worker route that acts as a narrow proxy for the assistant.

The worker handles:

- **origin validation** so requests only come from approved sites  
- **schema validation** for both chat and embeddings payloads  
- **rate limiting** to prevent abuse, with a bounded per-IP request window  
- **secret isolation** so the GitHub Models token never leaves the server boundary  
- **uniform response handling** across embeddings and chat completions  

In practical terms, the Worker is not trying to become an AI orchestration layer. It is intentionally narrow. The frontend decides what context to send, and the Worker decides whether the request is valid and safe to proxy.

This is a simple pattern, but it is the right one. It turns a frontend AI feature into a controlled service interface rather than an open client-side experiment.

## Why GitHub Models

GitHub Models was a strong fit for this implementation because it provided a clean way to call both embeddings and chat inference through a familiar developer workflow.

That let me keep the integration focused on product and architecture concerns:

- retrieving the right context  
- structuring the prompt correctly  
- validating the model output  
- controlling cost and abuse boundaries  

In other words, the interesting engineering problem here was never “how do I call an LLM API.” It was “how do I make the model answer the right question from the right evidence in a portfolio setting.”

## Guardrails and Deterministic Shortcuts

One of the mistakes people make with assistants is sending every query directly to the model.

I took a more disciplined approach.

Before the remote model is involved, the assistant first checks for:

- off-topic or adversarial prompts  
- prompt-injection style instructions  
- questions that can be answered deterministically from known patterns  

That means common questions like current role, core skills, education, or portfolio links can often be handled immediately without a full model round trip.

This improves latency, reduces token usage, and tightens correctness.

It also gives the assistant a more senior-engineered feel: use the model where it adds value, not where a clear rule-based answer already exists.

There is another important constraint in the implementation: even when the model is used, an answer is only accepted as a real answer if it comes back with valid citations that map to the provided snippet IDs. If the model returns an unsupported answer shape or cites content outside the retrieved context, the client treats that as a missing-information case instead of trusting it.

For development, I also added a local debug view that exposes the retrieval mode, the built retrieval query, the top-ranked snippets, and whether the closest-match fallback was used. That makes it much easier to inspect why a question failed, whether the wrong snippets were selected, or whether the model path failed after retrieval had already succeeded.

## Engineering Tradeoffs

There are a few deliberate tradeoffs in this design.

### 1. Static data over live repository introspection

The assistant answers from the published site content, not from repo activity, commit history, or unstated knowledge. That makes the experience more trustworthy even if it is narrower.

### 2. Retrieval-first over open-ended conversation

I optimized for factual grounding rather than personality. The assistant is there to help a visitor understand my work quickly and accurately.

### 3. Progressive enhancement over hard dependency

If embeddings fail, the assistant does not disappear. It falls back gracefully and still answers from keyword-ranked evidence. If the generation path fails after retrieval succeeds, it can still surface the closest grounded reference instead of throwing everything away.

### 4. Structured output over free-form generation

The response is expected in a constrained JSON shape with answer status and citations. That gives the UI something deterministic to render and makes failure modes easier to manage.

### 5. Thin worker over backend sprawl

I deliberately kept the backend boundary small. The Worker does not own retrieval, snippet construction, or portfolio-specific business logic. That keeps the moving parts understandable and makes the production surface easier to secure.

### 6. Freshness controls over forever-cached vectors

Client-side caching is great for latency, but AI features age in more ways than plain assets do. The underlying content can change, the embedding model can change, or the ranking logic can improve. That is why the assistant uses a content hash, a cache version, and a TTL together instead of assuming embeddings in local storage should live forever.

## What I Like About This Build

What I like most is that the system stays honest.

It does not pretend to know more than the portfolio actually says. It does not blur the line between retrieval and invention. And it does not rely on backend sprawl to deliver a relatively small but high-leverage user experience.

This is the kind of AI integration I find compelling in real systems: bounded, observable, useful, and aligned with the actual product surface.

## Closing Thoughts

There is a broader lesson here.

Good AI product engineering is rarely about adding a model to the stack and calling it innovation. The real work is in designing the data boundary, controlling failure modes, choosing where determinism should win, and making sure the system remains legible when something goes wrong.

That is what this assistant represents for me.

A portfolio is supposed to communicate capability. Building a resume-native assistant on top of structured content is a strong way to demonstrate not just that I can use AI tools, but that I can integrate them with sound engineering judgment.


Designing an assistant that answers from structured portfolio data, uses semantic retrieval over resume content, and safely proxies GitHub Models through Cloudflare Workers.

Building a Resume-Native AI Assistant for My Portfolio


## Context

Most personal websites start with hardcoded content directly inside components. This works initially, but quickly becomes difficult to maintain as the site grows.

Updating content requires code changes, deployments, and careful coordination between structure and presentation. Over time, even simple updates become unnecessarily complex.

This problem is not unique to portfolios. It appears in any system where content needs to evolve independently from application logic.

## The Problem

Traditional approaches often introduce friction:

- Content tightly coupled with UI components  
- No clear structure for managing different content types  
- Difficult to scale into blogs, case studies, or structured narratives  
- Lack of flexibility for non-developer editing  

The result is a system that works early but slows down iteration over time.

## Design Goals

The system was designed with a few clear goals:

- **Separation of content and presentation**  
- **Scalability across multiple content types** (blog, case studies, pages)  
- **Static generation for performance and simplicity**  
- **Git-based workflows for version control and traceability**  

## System Architecture

The core idea is simple: treat content as a first-class system.

## Content Layer

All content is stored in structured files:

- JSON for UI-driven sections (hero, stats)
- MDX for rich content (articles, case studies)

Example structure:


Building a Git-based CMS architecture using static generation, structured content, and a clean separation between content and UI.

Designing a Content System That Scales Beyond a Portfolio


## Context

Nonprofit organizations operate in an environment where financial systems are often fragmented, outdated, and difficult to scale. Many still rely on disconnected tools for payments, reporting, and donor management, which limits their ability to operate efficiently and make informed decisions.

At the same time, expectations around digital experiences have changed. Donors expect seamless payment flows, real-time confirmations, and support for modern channels such as mobile wallets and non-cash assets.

This creates a gap between how nonprofits operate and what modern financial infrastructure can enable.

## The Problem

Most existing systems fall short in three key areas:

- **Fragmented financial workflows**  
  Payments, reporting, and donor data are often handled across multiple systems with limited integration.

- **Limited support for modern payment methods**  
  Non-cash assets like stock, cryptocurrency, and donor-advised funds introduce complexity that traditional systems are not designed to handle.

- **Lack of real-time insights**  
  Data is often delayed, siloed, or difficult to query, limiting the ability to make timely decisions.

## What I Build

My work focuses on designing and building systems that address these challenges through:

### 1. Financial Infrastructure

Systems that support diverse donation flows:
- Card and ACH payments
- Mobile wallets (Apple Pay, Google Pay)
- Non-cash assets (stock, crypto, donor-advised funds)

These systems are designed for:
- reliability
- auditability
- high transaction volume

### 2. Data Pipelines and Processing Systems

To support large-scale data operations, I build:
- ETL pipelines for ingestion and normalization
- Queue-based processing systems for reliability and scalability
- Workflows that handle millions of records with retry and recovery mechanisms

These systems ensure that data remains consistent and usable across the platform.

### 3. AI-Driven Data Systems

I also work on systems that enable:
- natural language access to structured data
- secure query generation
- strict multi-tenant data isolation

The goal is to make complex financial data more accessible without compromising security or correctness.

## System Design Approach

Across these areas, my approach is consistent:

- **Event-driven architecture** to decouple systems and improve resilience  
- **Queue-based processing** to handle asynchronous workloads and failures  
- **Clear data boundaries** to maintain isolation in multi-tenant environments  
- **Practical tradeoffs** between consistency, performance, and complexity  

The focus is not just on building systems that work, but systems that continue to work as scale increases.

## Why This Matters

Financial infrastructure is foundational to how organizations operate.

For nonprofits, improving these systems means:
- better transparency in how funds are managed  
- improved donor experience  
- more efficient operations  
- stronger data-driven decision-making  

Small improvements in infrastructure can compound into significant impact across organizations and communities.

## Closing Thoughts

Building these systems is less about individual features and more about creating a foundation that can support growth, complexity, and change over time.

The problems are not purely technical—they sit at the intersection of systems design, product thinking, and real-world constraints.

That’s where I focus my work.

Designing systems that enable scalable, reliable, and intelligent financial operations for nonprofit organizations.

Building Financial Infrastructure for Modern Nonprofits


## Context

Data migration sounds simple until it isn’t.

When dealing with large datasets, even small inconsistencies can lead to incorrect records, duplication, or partial failures that are difficult to recover from.

## The Problem

Typical migration challenges include:

- inconsistent source data  
- partial failures mid-processing  
- duplicate records  
- lack of visibility into progress  

At scale, these issues compound quickly.

## Approach

### 1. Break Work Into Small Units

Instead of processing large datasets in one pass:

- split into smaller jobs  
- track progress per unit  
- allow retries at a granular level  

### 2. Parent-Child Job Model

Use a structured execution model:

- parent job tracks overall progress  
- child jobs process smaller chunks  

This enables:
- parallel execution  
- controlled retries  
- finalization after completion  

### 3. Idempotency by Design

Every operation should be safe to run multiple times:

- use unique identifiers  
- enforce deduplication  
- avoid side effects without checks  

### 4. Observability

Track:

- processed records  
- failed records  
- retry attempts  

This makes debugging and recovery practical.

## Tradeoffs

- increased system complexity  
- more infrastructure required for orchestration  
- additional overhead for tracking state  

## Why This Matters

Data migration is not just about moving data—it is about preserving correctness.

Systems that handle migration poorly introduce long-term data integrity issues.

## Closing Thoughts

A reliable migration system is one that can fail safely, recover predictably, and maintain correctness under load.

Building resilient pipelines to process large datasets with correctness, observability, and recoverability.

Projects

Building a Resume-Native AI Assistant for My Portfolio

Building Financial Infrastructure for Modern Nonprofits

Designing Data Migration Pipelines That Don’t Break at Scale