# postbasehq/postbase architecture

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

- Interactive diagram: https://gitdiagram.com/postbasehq/postbase
- Repository: https://github.com/postbasehq/postbase

## Overview

Postbase is a social-media scheduler with a dashboard, an AI drafting agent, and API/MCP access. The main workflow is to connect channels, compose or import posts, schedule them, and publish them to social platforms; users can then review analytics and manage workspaces, plans, and integrations. The graph also preserves the documented developer, bot, and marketing capabilities. Several routes and publishing modules were not excerpted, so their runtime links are shown only where documented or left unverified.

Main entry points: [`lib/api-core.ts`](https://github.com/postbasehq/postbase/blob/main/lib/api-core.ts) (Post API Core), [`app/api/mcp/route.ts`](https://github.com/postbasehq/postbase/blob/main/app/api/mcp/route.ts) (MCP Endpoint), [`app/(app)/layout.tsx`](https://github.com/postbasehq/postbase/blob/main/app/(app)/layout.tsx) (Scheduler Dashboard), [`components/DeveloperClient.tsx`](https://github.com/postbasehq/postbase/blob/main/components/DeveloperClient.tsx) (Developer Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace App"]
  node_dashboard["Scheduler Dashboard<br/>[layout.tsx]"]
end

subgraph group_publishing["Post Lifecycle"]
  node_composer["Post Composer<br/>[PostForm.tsx]"]
  node_media["Media Library<br/>[MediaLibrary.tsx]"]
  node_post_api["Post API Core<br/>[api-core.ts]"]
  node_post_store["Post Persistence<br/>[save-post.ts]"]
  node_publisher["Publishing Runtime<br/>[run.ts]"]
  node_queue["Publish Scheduler<br/>[route.ts]"]
end

subgraph group_channels["Social Channels"]
  node_channel_setup["Channel Connections"]
  node_platform_adapters["Platform Adapters<br/>[adapters.ts]"]
end

subgraph group_automation["AI And Developer Access"]
  node_agent_chat["Built-in Agent<br/>[route.ts]"]
  node_agent_runtime["Agent Runtime<br/>[tools.ts]"]
  node_mcp_api["MCP Endpoint<br/>[route.ts]"]
  node_oauth[("MCP OAuth<br/>[oauth.ts]")]
  node_rest_api["REST API"]
  node_developer_tools["Developer Settings"]
  node_postbots["Postbots"]
end

subgraph group_operations["Plans And Insights"]
  node_analytics["Analytics<br/>[report.ts]"]
  node_billing["Plans And Billing<br/>[billing-guard.ts]"]
  node_workspace_data[("Workspace Database<br/>[admin.ts]")]
end

node_user(("User"))
node_social_networks(("Social Networks"))
node_mcp_clients(("MCP Clients"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"composes"| node_composer
node_composer -.->|"creates posts"| node_post_api
node_post_api -->|"saves posts"| node_post_store
node_media -.->|"supplies media"| node_post_api
node_queue -.->|"runs publishing"| node_publisher
node_publisher -.->|"dispatches posts"| node_platform_adapters
node_platform_adapters -.->|"publishes to"| node_social_networks
node_user -->|"connects channels"| node_channel_setup
node_channel_setup -.->|"authorizes"| node_social_networks
node_dashboard -.->|"reviews results"| node_analytics
node_user -->|"asks agent"| node_agent_chat
node_agent_chat -.->|"runs agent"| node_agent_runtime
node_agent_runtime -.->|"creates posts"| node_post_api
node_mcp_clients -->|"calls tools"| node_mcp_api
node_mcp_api -->|"resolves tokens"| node_oauth
node_mcp_api -->|"creates posts"| node_post_api
node_rest_api -.->|"uses API core"| node_post_api
node_developer_tools -->|"configures access"| node_mcp_api
node_developer_tools -.->|"configures bots"| node_postbots
node_post_api -->|"checks access"| node_billing
node_billing -->|"reads plan data"| node_workspace_data

click node_dashboard "https://github.com/postbasehq/postbase/blob/main/app/(app)/layout.tsx"
click node_composer "https://github.com/postbasehq/postbase/blob/main/components/PostForm.tsx"
click node_media "https://github.com/postbasehq/postbase/blob/main/components/MediaLibrary.tsx"
click node_post_api "https://github.com/postbasehq/postbase/blob/main/lib/api-core.ts"
click node_post_store "https://github.com/postbasehq/postbase/blob/main/lib/publish/save-post.ts"
click node_publisher "https://github.com/postbasehq/postbase/blob/main/lib/publish/run.ts"
click node_queue "https://github.com/postbasehq/postbase/blob/main/app/api/cron/publish/route.ts"
click node_channel_setup "https://github.com/postbasehq/postbase/tree/main/app/api/connect"
click node_platform_adapters "https://github.com/postbasehq/postbase/blob/main/lib/publish/adapters.ts"
click node_analytics "https://github.com/postbasehq/postbase/blob/main/lib/analytics/report.ts"
click node_agent_chat "https://github.com/postbasehq/postbase/blob/main/app/api/agent/chat/route.ts"
click node_agent_runtime "https://github.com/postbasehq/postbase/blob/main/lib/agent/tools.ts"
click node_mcp_api "https://github.com/postbasehq/postbase/blob/main/app/api/mcp/route.ts"
click node_oauth "https://github.com/postbasehq/postbase/blob/main/lib/oauth.ts"
click node_rest_api "https://github.com/postbasehq/postbase/tree/main/app/api/v1"
click node_developer_tools "https://github.com/postbasehq/postbase/blob/main/components/DeveloperClient.tsx"
click node_postbots "https://github.com/postbasehq/postbase/tree/main/app/(bots)/bots"
click node_billing "https://github.com/postbasehq/postbase/blob/main/lib/billing-guard.ts"
click node_workspace_data "https://github.com/postbasehq/postbase/blob/main/lib/supabase/admin.ts"

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_dashboard,node_user,node_mcp_clients toneBlue
class node_composer,node_media,node_post_api,node_post_store,node_publisher,node_queue toneAmber
class node_channel_setup,node_platform_adapters toneMint
class node_agent_chat,node_agent_runtime,node_mcp_api,node_oauth,node_rest_api,node_developer_tools,node_postbots toneRose
class node_analytics,node_billing,node_workspace_data,node_social_networks toneIndigo
```

## Components

### Workspace App

- [Scheduler Dashboard](https://github.com/postbasehq/postbase/blob/main/app/(app)/layout.tsx): `app/(app)/layout.tsx`

### Post Lifecycle

- [Post Composer](https://github.com/postbasehq/postbase/blob/main/components/PostForm.tsx): `components/PostForm.tsx`
- [Media Library](https://github.com/postbasehq/postbase/blob/main/components/MediaLibrary.tsx): `components/MediaLibrary.tsx`
- [Post API Core](https://github.com/postbasehq/postbase/blob/main/lib/api-core.ts): `lib/api-core.ts`
- [Post Persistence](https://github.com/postbasehq/postbase/blob/main/lib/publish/save-post.ts): `lib/publish/save-post.ts`
- [Publishing Runtime](https://github.com/postbasehq/postbase/blob/main/lib/publish/run.ts): `lib/publish/run.ts`
- [Publish Scheduler](https://github.com/postbasehq/postbase/blob/main/app/api/cron/publish/route.ts): `app/api/cron/publish/route.ts`

### Social Channels

- [Channel Connections](https://github.com/postbasehq/postbase/tree/main/app/api/connect): `app/api/connect`
- [Platform Adapters](https://github.com/postbasehq/postbase/blob/main/lib/publish/adapters.ts): `lib/publish/adapters.ts`

### AI And Developer Access

- [Built-in Agent](https://github.com/postbasehq/postbase/blob/main/app/api/agent/chat/route.ts): `app/api/agent/chat/route.ts`
- [Agent Runtime](https://github.com/postbasehq/postbase/blob/main/lib/agent/tools.ts): `lib/agent/tools.ts`
- [MCP Endpoint](https://github.com/postbasehq/postbase/blob/main/app/api/mcp/route.ts): `app/api/mcp/route.ts`
- [MCP OAuth](https://github.com/postbasehq/postbase/blob/main/lib/oauth.ts): `lib/oauth.ts`
- [REST API](https://github.com/postbasehq/postbase/tree/main/app/api/v1): `app/api/v1`
- [Developer Settings](https://github.com/postbasehq/postbase/blob/main/components/DeveloperClient.tsx): `components/DeveloperClient.tsx`
- [Postbots](https://github.com/postbasehq/postbase/tree/main/app/(bots)/bots): `app/(bots)/bots`

### Plans And Insights

- [Analytics](https://github.com/postbasehq/postbase/blob/main/lib/analytics/report.ts): `lib/analytics/report.ts`
- [Plans And Billing](https://github.com/postbasehq/postbase/blob/main/lib/billing-guard.ts): `lib/billing-guard.ts`
- [Workspace Database](https://github.com/postbasehq/postbase/blob/main/lib/supabase/admin.ts): `lib/supabase/admin.ts`

### Other components

- **User**
- **Social Networks**
- **MCP Clients**

## Connections

- User → Scheduler Dashboard: uses (evidence: `README.md`)
- Scheduler Dashboard → Post Composer: composes (evidence: `README.md`)
- Post Composer → Post API Core: creates posts
- Post API Core → Post Persistence: saves posts (evidence: `lib/api-core.ts`)
- Media Library → Post API Core: supplies media
- Publish Scheduler → Publishing Runtime: runs publishing
- Publishing Runtime → Platform Adapters: dispatches posts
- Platform Adapters → Social Networks: publishes to
- User → Channel Connections: connects channels (evidence: `README.md`)
- Channel Connections → Social Networks: authorizes
- Scheduler Dashboard → Analytics: reviews results
- User → Built-in Agent: asks agent (evidence: `README.md`)
- Built-in Agent → Agent Runtime: runs agent (evidence: `app/api/agent/chat/route.ts`)
- Agent Runtime → Post API Core: creates posts
- MCP Clients → MCP Endpoint: calls tools (evidence: `README.md`)
- MCP Endpoint → MCP OAuth: resolves tokens (evidence: `app/api/mcp/route.ts`)
- MCP Endpoint → Post API Core: creates posts (evidence: `app/api/mcp/route.ts`)
- REST API → Post API Core: uses API core
- Developer Settings → MCP Endpoint: configures access (evidence: `README.md`)
- Developer Settings → Postbots: configures bots
- Post API Core → Plans And Billing: checks access (evidence: `lib/api-core.ts`)
- Plans And Billing → Workspace Database: reads plan data (evidence: `lib/billing-guard.ts`)
