# muazz7/muaz-ai-portfolio architecture

> Architecture diagram of the GitHub repository muazz7/muaz-ai-portfolio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muazz7/muaz-ai-portfolio
- Repository: https://github.com/muazz7/muaz-ai-portfolio

## Overview

Muaz AI Portfolio is a conversational portfolio: visitors ask about Mohammad Muaz, and the site streams grounded answers and interactive portfolio cards. The main path runs from the landing/chat interface through a validated, rate-limited API to either a configured model agent or local retrieval fallback, then returns text and tool events for browser rendering. README documents BM25 retrieval, persona prompting, provider options, and eight generative-UI capabilities. Sampled source confirms the route, stream client, and rendering boundary; some internal agent wiring is based on README documentation rather than inspected implementation.

Main entry points: [`src/app/api/chat/route.ts`](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/app/api/chat/route.ts) (Chat endpoint), [`src/lib/ai/agent.ts`](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/agent.ts) (Tool-calling agent), [`src/app/page.tsx`](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/app/page.tsx) (Landing page), [`src/hooks/use-portfolio-chat.ts`](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/hooks/use-portfolio-chat.ts) (Chat client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Visitor experience"]
  node_landing["Landing page<br/>[page.tsx]"]
  node_chatpage["Chat route<br/>[page.tsx]"]
  node_chatview["Chat view<br/>[chat-view.tsx]"]
  node_chatclient["Chat client"]
  node_messages["Message display<br/>[message-list.tsx]"]
  node_toolrenderer["Tool renderer<br/>[tool-renderer.tsx]"]
  node_fluid["Fluid background"]
  node_toolcards["Generative UI cards"]
end

subgraph group_service["Chat service"]
  node_endpoint["Chat endpoint<br/>[route.ts]"]
  node_protocol["Stream protocol<br/>[protocol.ts]"]
  node_ratelimit["Rate limiter<br/>[rate-limit.ts]"]
end

subgraph group_engine["Answer engines"]
  node_agent["Tool-calling agent<br/>[agent.ts]"]
  node_fallback["Local fallback<br/>[fallback.ts]"]
  node_retrieval["BM25 retrieval<br/>[retrieval.ts]"]
  node_prompt["Persona prompt<br/>[system-prompt.ts]"]
  node_provider["Provider adapter<br/>[provider.ts]"]
  node_tooldefs["Tool definitions<br/>[tools.ts]"]
end

subgraph group_portfolio["Portfolio content"]
  node_knowledge["Knowledge corpus<br/>[knowledge.ts]"]
  node_profile["Profile data<br/>[profile.ts]"]
  node_projectsdata["Project data<br/>[projects.ts]"]
  node_skillsdata["Skills data<br/>[skills.ts]"]
  node_questions["Suggested questions<br/>[questions.ts]"]
end

node_visitor(("Visitor"))
node_modelservice{{"AI provider"}}

node_visitor -->|"asks from"| node_landing
node_landing -->|"opens chat"| node_chatpage
node_chatpage -->|"renders"| node_chatview
node_visitor -->|"chats in"| node_chatview
node_chatview -->|"sends messages"| node_chatclient
node_chatclient -->|"POSTs messages"| node_endpoint
node_endpoint -->|"checks quota"| node_ratelimit
node_endpoint -->|"dispatches when configured"| node_agent
node_endpoint -->|"dispatches otherwise"| node_fallback
node_endpoint -->|"encodes events"| node_protocol
node_chatclient -->|"decodes events"| node_protocol
node_agent -->|"retrieves notes"| node_retrieval
node_retrieval -->|"scores corpus"| node_knowledge
node_agent -->|"uses persona"| node_prompt
node_agent -->|"requests completion"| node_provider
node_provider -.->|"calls configured model"| node_modelservice
node_agent -->|"executes selected tools"| node_tooldefs
node_fallback -->|"answers from notes"| node_retrieval
node_tooldefs -->|"reads profile"| node_profile
node_tooldefs -->|"reads projects"| node_projectsdata
node_tooldefs -->|"reads skills"| node_skillsdata
node_chatclient -->|"updates conversation"| node_messages
node_messages -->|"renders invocations"| node_toolrenderer
node_toolrenderer -->|"mounts matching card"| node_toolcards
node_landing -->|"shows suggestions"| node_questions
node_landing -->|"mounts background"| node_fluid

click node_landing "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/app/page.tsx"
click node_chatpage "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/app/chat/page.tsx"
click node_chatview "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/components/chat/chat-view.tsx"
click node_chatclient "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/hooks/use-portfolio-chat.ts"
click node_messages "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/components/chat/message-list.tsx"
click node_toolrenderer "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/components/chat/tool-renderer.tsx"
click node_fluid "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/fluid-simulation.ts"
click node_endpoint "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/app/api/chat/route.ts"
click node_protocol "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/protocol.ts"
click node_ratelimit "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/rate-limit.ts"
click node_agent "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/agent.ts"
click node_fallback "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/fallback.ts"
click node_retrieval "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/retrieval.ts"
click node_prompt "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/system-prompt.ts"
click node_provider "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/provider.ts"
click node_tooldefs "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/tools.ts"
click node_knowledge "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/data/knowledge.ts"
click node_profile "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/data/profile.ts"
click node_projectsdata "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/data/projects.ts"
click node_skillsdata "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/data/skills.ts"
click node_questions "https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/data/questions.ts"
click node_toolcards "https://github.com/muazz7/muaz-ai-portfolio/tree/main/src/components/tools"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_landing,node_chatpage,node_chatview,node_chatclient,node_messages,node_toolrenderer,node_fluid,node_toolcards toneBlue
class node_endpoint,node_protocol,node_ratelimit toneAmber
class node_agent,node_fallback,node_retrieval,node_prompt,node_provider,node_tooldefs toneMint
class node_knowledge,node_profile,node_projectsdata,node_skillsdata,node_questions toneRose
class node_visitor,node_modelservice toneIndigo
```

## Components

### Visitor experience

- [Landing page](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Chat route](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/app/chat/page.tsx): `src/app/chat/page.tsx`
- [Chat view](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/components/chat/chat-view.tsx): `src/components/chat/chat-view.tsx`
- [Chat client](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/hooks/use-portfolio-chat.ts): `src/hooks/use-portfolio-chat.ts`
- [Message display](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/components/chat/message-list.tsx): `src/components/chat/message-list.tsx`
- [Tool renderer](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/components/chat/tool-renderer.tsx): `src/components/chat/tool-renderer.tsx`
- [Fluid background](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/fluid-simulation.ts): `src/lib/fluid-simulation.ts`
- [Generative UI cards](https://github.com/muazz7/muaz-ai-portfolio/tree/main/src/components/tools): `src/components/tools`

### Chat service

- [Chat endpoint](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Stream protocol](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/protocol.ts): `src/lib/ai/protocol.ts`
- [Rate limiter](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/rate-limit.ts): `src/lib/ai/rate-limit.ts`

### Answer engines

- [Tool-calling agent](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/agent.ts): `src/lib/ai/agent.ts`
- [Local fallback](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/fallback.ts): `src/lib/ai/fallback.ts`
- [BM25 retrieval](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/retrieval.ts): `src/lib/ai/retrieval.ts`
- [Persona prompt](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/system-prompt.ts): `src/lib/ai/system-prompt.ts`
- [Provider adapter](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/provider.ts): `src/lib/ai/provider.ts`
- [Tool definitions](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/ai/tools.ts): `src/lib/ai/tools.ts`

### Portfolio content

- [Knowledge corpus](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/data/knowledge.ts): `src/lib/data/knowledge.ts`
- [Profile data](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/data/profile.ts): `src/lib/data/profile.ts`
- [Project data](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/data/projects.ts): `src/lib/data/projects.ts`
- [Skills data](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/data/skills.ts): `src/lib/data/skills.ts`
- [Suggested questions](https://github.com/muazz7/muaz-ai-portfolio/blob/main/src/lib/data/questions.ts): `src/lib/data/questions.ts`

### Other components

- **Visitor**
- **AI provider**

## Connections

- Visitor → Landing page: asks from
- Landing page → Chat route: opens chat
- Chat route → Chat view: renders
- Visitor → Chat view: chats in
- Chat view → Chat client: sends messages
- Chat client → Chat endpoint: POSTs messages
- Chat endpoint → Rate limiter: checks quota
- Chat endpoint → Tool-calling agent: dispatches when configured
- Chat endpoint → Local fallback: dispatches otherwise
- Chat endpoint → Stream protocol: encodes events
- Chat client → Stream protocol: decodes events
- Tool-calling agent → BM25 retrieval: retrieves notes
- BM25 retrieval → Knowledge corpus: scores corpus
- Tool-calling agent → Persona prompt: uses persona
- Tool-calling agent → Provider adapter: requests completion
- Provider adapter → AI provider: calls configured model
- Tool-calling agent → Tool definitions: executes selected tools
- Local fallback → BM25 retrieval: answers from notes
- Tool definitions → Profile data: reads profile
- Tool definitions → Project data: reads projects
- Tool definitions → Skills data: reads skills
- Chat client → Message display: updates conversation
- Message display → Tool renderer: renders invocations
- Tool renderer → Generative UI cards: mounts matching card
- Landing page → Suggested questions: shows suggestions
- Landing page → Fluid background: mounts background