# raahuljohn/portfolio_ai_agent architecture

> Architecture diagram of the GitHub repository raahuljohn/portfolio_ai_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raahuljohn/portfolio_ai_agent
- Repository: https://github.com/raahuljohn/portfolio_ai_agent

## Overview

1. **Overall shape**
   - This repo is split into two loosely coupled runtimes: a **Botpress ADK agent backend** at the repo root and a **React/Vite web frontend** in `frontend/`.
   - The backend is the source of truth for conversation logic and knowledge access; the frontend is only a client that connects to the deployed bot via Botpress webchat.

2. **Backend purpose**
   - The root project implements a **portfolio assistant** for “John,” answering questions about work experience, education, skills, projects, and contact info.
   - It is built with **TypeScript + Bun** and Botpress tooling (`@botpress/runtime` / ADK), so the core runtime is an agent platform rather than a traditional web server.

3. **Conversation layer**
   - `src/conversations/` is the main request-handling boundary.
   - Incoming messages from supported channels are routed here, where the agent applies its instructions and retrieves relevant information from the knowledge base before producing a response.

4. **Knowledge base subsystem**
   - `src/knowledge/` contains the content sources that power answers: `work-experience.md`, `education.md`, `skills.md`, `projects.md`, and `contact.md`.
   - `src/knowledge/index.ts` likely aggregates these sources for Botpress ingestion.
   - The data flow is: **LinkedIn-derived markdown content → Botpress knowledge indexing → conversation responses**.

5. **Scheduled refresh / indexing**
   - `src/workflows/` holds scheduled automation, and the README says it **re-indexes the knowledge base every 6 hours**.
   - This is the main maintenance path that keeps the agent’s answer base in sync without manual intervention.

6. **Integrations and channels**
   - The agent is configured to listen on **webchat** and **chat** channels, with a **browser** integration also enabled in `agent.config.ts`.
   - These are the external ingress points into the agent; the frontend uses webchat, while Botpress can also be accessed through generic chat or browser automation contexts.

7. **Agent configuration boundary**
   - `agent.config.ts` and `agent.json` define deployment/runtime metadata such as models, state, and integrations.
   - The README indicates two model roles: an autonomous model (`google-ai:gemini-2.5-pro`) and another model (`openai:gpt-4.1-mini`) used for a named mode/path (`zai`), which suggests model selection is part of the agent orchestration rather than the UI.

8. **Placeholder extensibility points**
   - `src/actions/`, `src/tables/`, and `src/triggers/` are present but appear to be scaffolding or placeholders.
   - Architecturally, these mark the standard Botpress extension points for callable actions, persistent schemas, and event subscriptions, even if they are not heavily used yet.

9. **Frontend application**
   - `frontend/` is a separate **React 19 + Vite + Tailwind CSS** app.
   - It provides the user-facing interface and does not contain the agent logic itself; instead, it embeds or connects to Botpress webchat.

10. **Frontend-to-agent connection**
   - `frontend/src/config/constants.ts` likely stores the Botpress **client ID** used by `@botpress/webchat`.
   - The data flow here is: **browser user → React UI/webchat SDK → Botpress cloud agent → conversation handler → knowledge base → response back to webchat**.

11. **UI composition**
   - `frontend/src/App.tsx` is the main UI shell.
   - `frontend/src/components/TextRenderer.tsx` suggests the frontend customizes how bot messages are rendered, while assets and CSS files handle presentation and motion polish.

12. **Build and deployment boundaries**
   - The backend is managed with **Bun** and deployed via Botpress ADK (`adk dev`, `adk deploy`).
   - The frontend uses its own Node-based toolchain (`npm`, Vite) and is built/deployed independently from the agent, which keeps the chat UI and bot runtime decoupled.

13. **Architecture summary for a diagram**
   - A clean diagram would show:
     - **User browser**
     - **React/Vite frontend**
     - **Botpress webchat SDK**
     - **Botpress cloud agent**
     - **Conversation handler**
     - **Knowledge documents**
     - **Scheduled indexing workflow**
   - The main system dependency is the knowledge base; the main runtime boundary is between the browser UI and the Botpress-hosted agent.

Main entry points: [`src/knowledge/index.ts`](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/index.ts) (KB index), [`src/conversations/index.ts`](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/conversations/index.ts) (Conversation layer), [`frontend/src/App.tsx`](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/frontend/src/App.tsx) (App shell), [`agent.config.ts`](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/agent.config.ts) (Agent config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Botpress agent"]
  node_agent_config["Agent config<br/>runtime config<br/>[agent.config.ts]"]
  node_agent_meta["Agent manifest<br/>deployment metadata<br/>[agent.json]"]
  node_conversations["Conversation layer<br/>message routing<br/>[index.ts]"]
  node_actions["Actions<br/>extension point<br/>[index.ts]"]
  node_tables[("Tables<br/>extension point<br/>[index.ts]")]
  node_triggers{{"Triggers<br/>extension point<br/>[index.ts]"}}
  node_workflows{{"Refresh workflow<br/>scheduled automation<br/>[index.ts]"}}
end

subgraph group_frontend["React client"]
  node_frontend_app["App shell<br/>react ui<br/>[App.tsx]"]
  node_webchat_cfg["Botpress ID<br/>client config<br/>[constants.ts]"]
  node_text_renderer["Text renderer<br/>ui component<br/>[TextRenderer.tsx]"]
  node_frontend_entry["UI entry<br/>bootstrap<br/>[main.tsx]"]
end

subgraph group_knowledge["Knowledge base"]
  node_kb_index["KB index<br/>knowledge aggregation<br/>[index.ts]"]
  node_work_exp["Work history<br/>markdown source<br/>[work-experience.md]"]
  node_education["Education<br/>markdown source<br/>[education.md]"]
  node_skills["Skills<br/>markdown source<br/>[skills.md]"]
  node_projects["Projects<br/>markdown source<br/>[projects.md]"]
  node_contact["Contact<br/>markdown source<br/>[contact.md]"]
end

node_user(("User browser<br/>external user"))

node_user -->|"opens UI"| node_frontend_app
node_frontend_entry -->|"mounts"| node_frontend_app
node_frontend_app -->|"loads config"| node_webchat_cfg
node_frontend_app -->|"renders messages"| node_text_renderer
node_frontend_app -->|"sends chat"| node_conversations
node_agent_config -->|"routes runtime"| node_conversations
node_agent_meta -->|"supports"| node_agent_config
node_conversations -->|"queries knowledge"| node_kb_index
node_kb_index -->|"includes"| node_work_exp
node_kb_index -->|"includes"| node_education
node_kb_index -->|"includes"| node_skills
node_kb_index -->|"includes"| node_projects
node_kb_index -->|"includes"| node_contact
node_workflows -->|"re-indexes"| node_kb_index
node_conversations -.->|"may call"| node_actions
node_conversations -.->|"emits events"| node_triggers
node_conversations -.->|"stores state"| node_tables

click node_agent_config "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/agent.config.ts"
click node_agent_meta "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/agent.json"
click node_conversations "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/conversations/index.ts"
click node_actions "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/actions/index.ts"
click node_tables "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/tables/index.ts"
click node_triggers "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/triggers/index.ts"
click node_workflows "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/workflows/index.ts"
click node_kb_index "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/index.ts"
click node_work_exp "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/work-experience.md"
click node_education "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/education.md"
click node_skills "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/skills.md"
click node_projects "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/projects.md"
click node_contact "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/contact.md"
click node_frontend_app "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/frontend/src/App.tsx"
click node_webchat_cfg "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/frontend/src/config/constants.ts"
click node_text_renderer "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/frontend/src/components/TextRenderer.tsx"
click node_frontend_entry "https://github.com/raahuljohn/portfolio_ai_agent/blob/main/frontend/src/main.tsx"

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_agent_config,node_agent_meta,node_conversations,node_actions,node_tables,node_triggers,node_workflows toneBlue
class node_frontend_app,node_webchat_cfg,node_text_renderer,node_frontend_entry toneAmber
class node_kb_index,node_work_exp,node_education,node_skills,node_projects,node_contact toneMint
class node_user toneNeutral
```

## Components

### Botpress agent

Root Bun/TypeScript runtime that hosts the portfolio assistant.

- [Agent config](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/agent.config.ts): runtime config · Botpress deployment and model configuration boundary. · `agent.config.ts`
- [Agent manifest](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/agent.json): deployment metadata · Agent-level metadata and orchestration settings. · `agent.json`
- [Conversation layer](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/conversations/index.ts): message routing · Main request-handling boundary for incoming chat messages. · `src/conversations/index.ts`
- [Actions](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/actions/index.ts): extension point · Callable Botpress action surface for future automation. · `src/actions/index.ts`
- [Tables](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/tables/index.ts): extension point · Persistent data/schema extension point. · `src/tables/index.ts`
- [Triggers](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/triggers/index.ts): extension point · Event subscription and automation entry point. · `src/triggers/index.ts`
- [Refresh workflow](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/workflows/index.ts): scheduled automation · Scheduled job that re-indexes the knowledge base. · `src/workflows/index.ts`

### React client

Separate Vite app that embeds and renders the webchat experience.

- [App shell](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/frontend/src/App.tsx): react ui · Main React/Vite application shell. · `frontend/src/App.tsx`
- [Botpress ID](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/frontend/src/config/constants.ts): client config · Client-side Botpress webchat configuration. · `frontend/src/config/constants.ts`
- [Text renderer](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/frontend/src/components/TextRenderer.tsx): ui component · Custom rendering for bot messages. · `frontend/src/components/TextRenderer.tsx`
- [UI entry](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/frontend/src/main.tsx): bootstrap · Front-end entrypoint that mounts the React app. · `frontend/src/main.tsx`

### Knowledge base

Markdown content sources indexed for answers.

- [KB index](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/index.ts): knowledge aggregation · Aggregates markdown sources for Botpress ingestion. · `src/knowledge/index.ts`
- [Work history](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/work-experience.md): markdown source · Work experience content for the assistant. · `src/knowledge/work-experience.md`
- [Education](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/education.md): markdown source · Education content for the assistant. · `src/knowledge/education.md`
- [Skills](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/skills.md): markdown source · Skills content for the assistant. · `src/knowledge/skills.md`
- [Projects](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/projects.md): markdown source · Projects content for the assistant. · `src/knowledge/projects.md`
- [Contact](https://github.com/raahuljohn/portfolio_ai_agent/blob/main/src/knowledge/contact.md): markdown source · Contact details content for the assistant. · `src/knowledge/contact.md`

### Other components

- **User browser**: external user · Person visiting the portfolio chat experience.

## Connections

- User browser → App shell: opens UI · Browser user starts at the React interface.
- UI entry → App shell: mounts · Bootstraps the application shell.
- App shell → Botpress ID: loads config · UI reads Botpress client configuration.
- App shell → Text renderer: renders messages · Customizes chat message presentation.
- App shell → Conversation layer: sends chat · Embedded webchat relays user messages to the agent.
- Agent config → Conversation layer: routes runtime · Agent config defines the runtime boundary and model behavior.
- Agent manifest → Agent config: supports · Manifest complements the runtime configuration.
- Conversation layer → KB index: queries knowledge · Conversation logic resolves responses from indexed content.
- KB index → Work history: includes · Aggregates work-experience markdown.
- KB index → Education: includes · Aggregates education markdown.
- KB index → Skills: includes · Aggregates skills markdown.
- KB index → Projects: includes · Aggregates projects markdown.
- KB index → Contact: includes · Aggregates contact markdown.
- Refresh workflow → KB index: re-indexes · Scheduled maintenance keeps knowledge fresh.
- Conversation layer → Actions: may call · Conversation flows can invoke actions when needed.
- Conversation layer → Triggers: emits events · Conversation runtime participates in trigger-driven automation.
- Conversation layer → Tables: stores state · Persistent schemas can support conversation state.
