# vijay-baunthiyal/post_generator architecture

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

- Interactive diagram: https://gitdiagram.com/vijay-baunthiyal/post_generator
- Repository: https://github.com/vijay-baunthiyal/post_generator

## Overview

#### Purpose and Top-Level Entry Points
This is a two-process AI-agent demo: a Next.js 15 frontend presents CopilotKit-powered interfaces, while a Python FastAPI service runs Gemini/LangGraph agents. The application supports social-post generation and website technology-stack analysis.

Frontend entry/layout: `app/layout.tsx`, `app/page.tsx`, `app/wrapper.tsx`. Backend entry: `agent/main.py`.

#### Frontend Application Shell
The Next.js App Router provides the shared document layout, global styling, theme/UI context, and agent integration wrapper. The wrapper is the likely boundary where CopilotKit client capabilities are configured for descendant pages.

Key paths: `app/layout.tsx`, `app/wrapper.tsx`, `app/contexts/LayoutContext.tsx`.

#### Task-Specific User Experiences
The frontend separates the two agent workflows into dedicated routes:
- Post generation accepts user context and renders platform-specific LinkedIn/X content.
- Stack analysis accepts a site URL and presents inferred technologies and tool activity.

Key paths: `app/post-generator/page.tsx`, `app/stack-analyzer/page.tsx`, `components/ui/linkedin-post.tsx`, `components/ui/stack-analysis-cards.tsx`.

#### CopilotKit and Chat API Boundary
Next.js route handlers expose CopilotKit and chat endpoints to the browser. These form the frontend server boundary for agent conversations/actions and likely proxy or coordinate with the Python agent runtime.

Key paths: `app/api/copilotkit/route.ts`, `app/api/chat/route.ts`, `app/prompts/prompts.ts`.

#### Python Agent Service
The FastAPI backend hosts the executable agent runtime. It contains distinct agent definitions for each task and shared prompt material. The frontend requires this service to be running, making it the primary AI-execution boundary rather than a purely client-side Gemini integration.

Key paths: `agent/main.py`, `agent/posts_generator_agent.py`, `agent/stack_agent.py`, `agent/prompts.py`.

#### Agent Processing Flow
Requests flow from task pages through CopilotKit/API handlers to FastAPI agents. Each agent uses LangGraph orchestration and Google Gemini inference, then returns structured/conversational outputs for UI rendering. The post agent transforms supplied context into LinkedIn and Twitter/X copy; the stack agent analyzes a supplied URL to identify frameworks, libraries, and infrastructure.

Key paths: `agent/posts_generator_agent.py`, `agent/stack_agent.py`, `components/ui/x-post.tsx`, `components/ui/tool-logs.tsx`.

#### Runtime and External Dependencies
The frontend runs on Node.js/Next.js and is managed with pnpm (`package.json`, `pnpm-workspace.yaml`). The backend is a Python project (`agent/pyproject.toml`) served via FastAPI. Gemini access depends on `GOOGLE_API_KEY`; CopilotKit links UI interactions to agent workflows; LangGraph structures agent execution. Deployment is compatible with the hosted Vercel frontend, while the Python service must be independently available.

Key paths: `package.json`, `agent/pyproject.toml`, `next.config.mjs`.

Main entry points: [`agent/stack_agent.py`](https://github.com/vijay-baunthiyal/post_generator/blob/main/agent/stack_agent.py) (Stack agent), [`app/wrapper.tsx`](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/wrapper.tsx) (CopilotKit wrapper), [`app/stack-analyzer/page.tsx`](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/stack-analyzer/page.tsx) (Stack analyzer), [`agent/main.py`](https://github.com/vijay-baunthiyal/post_generator/blob/main/agent/main.py) (Agent runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js frontend"]
  node_app_shell["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_copilot_wrapper["CopilotKit wrapper<br/>client integration<br/>[wrapper.tsx]"]
  node_layout_context["Layout context<br/>UI context<br/>[LayoutContext.tsx]"]
  node_home_page["Home page<br/>route<br/>[page.tsx]"]
  node_post_page["Post generator<br/>route<br/>[page.tsx]"]
  node_stack_page["Stack analyzer<br/>route<br/>[page.tsx]"]
  node_post_cards["Post renderers<br/>UI components<br/>[linkedin-post.tsx]"]
  node_stack_results["Analysis results<br/>UI components"]
  node_tool_logs["Tool logs<br/>UI component<br/>[tool-logs.tsx]"]
end

subgraph group_api["Next.js API boundary"]
  node_copilot_api["CopilotKit endpoint<br/>route handler<br/>[route.ts]"]
  node_chat_api["Chat endpoint<br/>route handler<br/>[route.ts]"]
  node_frontend_prompts["Frontend prompts<br/>prompt definitions<br/>[prompts.ts]"]
end

subgraph group_backend["Python agent service"]
  node_fastapi_service["Agent runtime<br/>FastAPI service<br/>[main.py]"]
  node_post_agent{{"Post agent<br/>LangGraph agent"}}
  node_stack_agent{{"Stack agent<br/>LangGraph agent<br/>[stack_agent.py]"}}
  node_agent_prompts["Agent prompts<br/>prompt definitions<br/>[prompts.py]"]
end

node_gemini(("Google Gemini<br/>inference API"))

node_app_shell -->|"wraps"| node_copilot_wrapper
node_app_shell -->|"provides"| node_layout_context
node_app_shell -->|"serves"| node_home_page
node_copilot_wrapper -->|"enables agent UI"| node_post_page
node_copilot_wrapper -->|"enables agent UI"| node_stack_page
node_post_page -->|"renders output"| node_post_cards
node_stack_page -->|"renders output"| node_stack_results
node_stack_page -->|"shows activity"| node_tool_logs
node_copilot_wrapper -->|"agent requests"| node_copilot_api
node_post_page -->|"chat requests"| node_chat_api
node_stack_page -->|"analysis requests"| node_chat_api
node_frontend_prompts -.->|"supplies instructions"| node_copilot_api
node_copilot_api -->|"forwards workflows"| node_fastapi_service
node_chat_api -->|"forwards requests"| node_fastapi_service
node_fastapi_service -->|"runs post workflow"| node_post_agent
node_fastapi_service -->|"runs analysis workflow"| node_stack_agent
node_agent_prompts -.->|"guides"| node_post_agent
node_agent_prompts -.->|"guides"| node_stack_agent
node_post_agent -->|"LangGraph inference"| node_gemini
node_stack_agent -->|"LangGraph inference"| node_gemini
node_post_agent -->|"structured copy"| node_post_cards
node_stack_agent -->|"technology findings"| node_stack_results
node_stack_agent -->|"tool events"| node_tool_logs

click node_app_shell "https://github.com/vijay-baunthiyal/post_generator/blob/main/app/layout.tsx"
click node_copilot_wrapper "https://github.com/vijay-baunthiyal/post_generator/blob/main/app/wrapper.tsx"
click node_layout_context "https://github.com/vijay-baunthiyal/post_generator/blob/main/app/contexts/LayoutContext.tsx"
click node_home_page "https://github.com/vijay-baunthiyal/post_generator/blob/main/app/page.tsx"
click node_post_page "https://github.com/vijay-baunthiyal/post_generator/blob/main/app/post-generator/page.tsx"
click node_stack_page "https://github.com/vijay-baunthiyal/post_generator/blob/main/app/stack-analyzer/page.tsx"
click node_post_cards "https://github.com/vijay-baunthiyal/post_generator/blob/main/components/ui/linkedin-post.tsx"
click node_stack_results "https://github.com/vijay-baunthiyal/post_generator/blob/main/components/ui/stack-analysis-cards.tsx"
click node_tool_logs "https://github.com/vijay-baunthiyal/post_generator/blob/main/components/ui/tool-logs.tsx"
click node_copilot_api "https://github.com/vijay-baunthiyal/post_generator/blob/main/app/api/copilotkit/route.ts"
click node_chat_api "https://github.com/vijay-baunthiyal/post_generator/blob/main/app/api/chat/route.ts"
click node_frontend_prompts "https://github.com/vijay-baunthiyal/post_generator/blob/main/app/prompts/prompts.ts"
click node_fastapi_service "https://github.com/vijay-baunthiyal/post_generator/blob/main/agent/main.py"
click node_post_agent "https://github.com/vijay-baunthiyal/post_generator/blob/main/agent/posts_generator_agent.py"
click node_stack_agent "https://github.com/vijay-baunthiyal/post_generator/blob/main/agent/stack_agent.py"
click node_agent_prompts "https://github.com/vijay-baunthiyal/post_generator/blob/main/agent/prompts.py"

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_app_shell,node_copilot_wrapper,node_layout_context,node_home_page,node_post_page,node_stack_page,node_post_cards,node_stack_results,node_tool_logs toneBlue
class node_copilot_api,node_chat_api,node_frontend_prompts toneAmber
class node_fastapi_service,node_post_agent,node_stack_agent,node_agent_prompts toneMint
class node_gemini toneNeutral
```

## Components

### Next.js frontend

App Router UI and browser-facing integration.

- [App shell](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/layout.tsx): Next.js layout · Provides shared layout, styling, and UI context. · `app/layout.tsx`
- [CopilotKit wrapper](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/wrapper.tsx): client integration · Configures agent capabilities for descendant pages. · `app/wrapper.tsx`
- [Layout context](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/contexts/LayoutContext.tsx): UI context · `app/contexts/LayoutContext.tsx`
- [Home page](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/page.tsx): route · `app/page.tsx`
- [Post generator](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/post-generator/page.tsx): route · Collects context and displays generated social copy. · `app/post-generator/page.tsx`
- [Stack analyzer](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/stack-analyzer/page.tsx): route · Accepts a URL and presents inferred technologies. · `app/stack-analyzer/page.tsx`
- [Post renderers](https://github.com/vijay-baunthiyal/post_generator/blob/main/components/ui/linkedin-post.tsx): UI components · Renders LinkedIn and X content. · `components/ui/linkedin-post.tsx`
- [Analysis results](https://github.com/vijay-baunthiyal/post_generator/blob/main/components/ui/stack-analysis-cards.tsx): UI components · Shows technology cards and agent tool activity. · `components/ui/stack-analysis-cards.tsx`
- [Tool logs](https://github.com/vijay-baunthiyal/post_generator/blob/main/components/ui/tool-logs.tsx): UI component · `components/ui/tool-logs.tsx`

### Next.js API boundary

Server handlers for CopilotKit and chat requests.

- [CopilotKit endpoint](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/api/copilotkit/route.ts): route handler · Browser-facing CopilotKit conversation and action boundary. · `app/api/copilotkit/route.ts`
- [Chat endpoint](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/api/chat/route.ts): route handler · Chat request boundary for agent interactions. · `app/api/chat/route.ts`
- [Frontend prompts](https://github.com/vijay-baunthiyal/post_generator/blob/main/app/prompts/prompts.ts): prompt definitions · `app/prompts/prompts.ts`

### Python agent service

FastAPI-hosted task agents and orchestration.

- [Agent runtime](https://github.com/vijay-baunthiyal/post_generator/blob/main/agent/main.py): FastAPI service · Independently deployed Python execution boundary. · `agent/main.py`
- [Post agent](https://github.com/vijay-baunthiyal/post_generator/blob/main/agent/posts_generator_agent.py): LangGraph agent · Produces LinkedIn and X copy from supplied context. · `agent/posts_generator_agent.py`
- [Stack agent](https://github.com/vijay-baunthiyal/post_generator/blob/main/agent/stack_agent.py): LangGraph agent · Analyzes URLs for frameworks, libraries, and infrastructure. · `agent/stack_agent.py`
- [Agent prompts](https://github.com/vijay-baunthiyal/post_generator/blob/main/agent/prompts.py): prompt definitions · `agent/prompts.py`

### Other components

- **Google Gemini**: inference API · Model inference authenticated with GOOGLE_API_KEY.

## Connections

- App shell → CopilotKit wrapper: wraps
- App shell → Layout context: provides
- App shell → Home page: serves
- CopilotKit wrapper → Post generator: enables agent UI
- CopilotKit wrapper → Stack analyzer: enables agent UI
- Post generator → Post renderers: renders output
- Stack analyzer → Analysis results: renders output
- Stack analyzer → Tool logs: shows activity
- CopilotKit wrapper → CopilotKit endpoint: agent requests
- Post generator → Chat endpoint: chat requests
- Stack analyzer → Chat endpoint: analysis requests
- Frontend prompts → CopilotKit endpoint: supplies instructions
- CopilotKit endpoint → Agent runtime: forwards workflows
- Chat endpoint → Agent runtime: forwards requests
- Agent runtime → Post agent: runs post workflow
- Agent runtime → Stack agent: runs analysis workflow
- Agent prompts → Post agent: guides
- Agent prompts → Stack agent: guides
- Post agent → Google Gemini: LangGraph inference
- Stack agent → Google Gemini: LangGraph inference
- Post agent → Post renderers: structured copy
- Stack agent → Analysis results: technology findings
- Stack agent → Tool logs: tool events