How raahuljohn/portfolio_ai_agent works
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: knowledge/index.ts KB index · conversations/index.ts Conversation layer · App.tsx App shell · agent.config.ts Agent config
Components 18
Botpress agent
Root Bun/TypeScript runtime that hosts the portfolio assistant.
- Agent config · Botpress deployment and model configuration boundary.
agent.config.ts - Agent manifest · Agent-level metadata and orchestration settings.
agent.json - Conversation layer · Main request-handling boundary for incoming chat messages.
src/conversations/index.ts - Actions · Callable Botpress action surface for future automation.
src/actions/index.ts - Tables · Persistent data/schema extension point.
src/tables/index.ts - Triggers · Event subscription and automation entry point.
src/triggers/index.ts - Refresh workflow · 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 · Main React/Vite application shell.
frontend/src/App.tsx - Botpress ID · Client-side Botpress webchat configuration.
frontend/src/config/constants.ts - Text renderer · Custom rendering for bot messages.
frontend/src/components/TextRenderer.tsx - UI entry · Front-end entrypoint that mounts the React app.
frontend/src/main.tsx
Knowledge base
Markdown content sources indexed for answers.
- KB index · Aggregates markdown sources for Botpress ingestion.
src/knowledge/index.ts - Work history · Work experience content for the assistant.
src/knowledge/work-experience.md - Education · Education content for the assistant.
src/knowledge/education.md - Skills · Skills content for the assistant.
src/knowledge/skills.md - Projects · Projects content for the assistant.
src/knowledge/projects.md - Contact · Contact details content for the assistant.
src/knowledge/contact.md
Other components
- User browser · Person visiting the portfolio chat experience.
Connections 17
- 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.