# lumizone/postsider architecture

> Architecture diagram of the GitHub repository lumizone/postsider, 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/lumizone/postsider
- Repository: https://github.com/lumizone/postsider

## Overview

PostSider is a self-hostable social publishing platform: people plan content, route it for approval, and schedule publication across connected channels; automation clients can use the same public API. The graph preserves the documented calendar, content, team, security, analytics, webhook, and AI-agent capabilities. Source excerpts show MCP tool-to-client and HTTP-server wiring, but most backend routes and workflow implementations were not sampled, so several product connections rely on README statements rather than inferred internal calls.

Main entry points: [`apps/frontend/src/components/calendar.tsx`](https://github.com/lumizone/postsider/blob/main/apps/frontend/src/components/calendar.tsx) (Calendar and posts), [`apps/backend/src/api/routes/posts.controller.ts`](https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/posts.controller.ts) (Post routes), [`apps/backend/src/public-api/routes/v1/public.integrations.controller.ts`](https://github.com/lumizone/postsider/blob/main/apps/backend/src/public-api/routes/v1/public.integrations.controller.ts) (Public API), [`apps/mcp/src/server.ts`](https://github.com/lumizone/postsider/blob/main/apps/mcp/src/server.ts) (MCP tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Planning and publishing"]
  node_calendar["Calendar and posts<br/>[calendar.tsx]"]
  node_previews["Platform previews"]
  node_channelui["Channel UI<br/>[channel-avatar.tsx]"]
end

subgraph group_platform["Platform services"]
  node_postapi["Post routes"]
  node_approvalapi["Approval routes"]
  node_integrationapi["Channel routes"]
  node_publicapi["Public API"]
  node_postdata["Post services<br/>[posts.service.ts]"]
  node_connectors["Connector registry"]
  node_storage["Media storage"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_mfa["MFA service<br/>[mfa.service.ts]"]
  node_analytics["Analytics routes"]
  node_webhooks["Webhook routes"]
  node_billing["Billing service<br/>[polar.service.ts]"]
end

subgraph group_automation["Automation interfaces"]
  node_mcpserver["MCP tools<br/>[server.ts]"]
  node_mcpclient["API client<br/>[client.ts]"]
  node_httpmcp["MCP HTTP<br/>[server.ts]"]
  node_sdk["Node SDK<br/>[index.ts]"]
end

subgraph group_operations["Background operations"]
  node_orchestrator["Workflow worker<br/>[main.ts]"]
  node_webhookdelivery["Webhook delivery"]
  node_bootstrap["Admin bootstrap<br/>[bootstrap.admin.ts]"]
end

node_human(("Team member"))
node_agent(("AI agent"))

node_human -->|"plans content"| node_calendar
node_calendar -->|"submits posts"| node_postapi
node_human -->|"reviews drafts"| node_approvalapi
node_calendar -->|"previews posts"| node_previews
node_calendar -->|"chooses channels"| node_channelui
node_postapi -.->|"manages posts"| node_postdata
node_integrationapi -->|"uses connectors"| node_connectors
node_human -->|"connects channels"| node_integrationapi
node_postapi -.->|"handles media"| node_storage
node_agent -->|"uses tools"| node_mcpserver
node_mcpserver -->|"calls API client"| node_mcpclient
node_httpmcp -->|"hosts tools"| node_mcpserver
node_mcpclient -->|"calls REST API"| node_publicapi
node_sdk -->|"calls REST API"| node_publicapi
node_human -->|"signs in"| node_auth
node_auth -.->|"supports MFA"| node_mfa
node_human -->|"reviews analytics"| node_analytics
node_publicapi -->|"manages subscriptions"| node_webhooks
node_webhookdelivery -.->|"delivers events"| node_webhooks
node_orchestrator -.->|"runs activity"| node_webhookdelivery
node_human -.->|"manages plan"| node_billing
node_human -->|"creates administrator"| node_bootstrap

click node_calendar "https://github.com/lumizone/postsider/blob/main/apps/frontend/src/components/calendar.tsx"
click node_previews "https://github.com/lumizone/postsider/blob/main/apps/frontend/src/components/post-preview/post-preview-panel.tsx"
click node_channelui "https://github.com/lumizone/postsider/blob/main/apps/frontend/src/components/channel-avatar.tsx"
click node_postapi "https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/posts.controller.ts"
click node_approvalapi "https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/approval.controller.ts"
click node_integrationapi "https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/integrations.controller.ts"
click node_publicapi "https://github.com/lumizone/postsider/blob/main/apps/backend/src/public-api/routes/v1/public.integrations.controller.ts"
click node_postdata "https://github.com/lumizone/postsider/blob/main/libraries/nestjs-libraries/src/database/prisma/posts/posts.service.ts"
click node_connectors "https://github.com/lumizone/postsider/blob/main/libraries/nestjs-libraries/src/integrations/integration.manager.ts"
click node_storage "https://github.com/lumizone/postsider/blob/main/libraries/nestjs-libraries/src/upload/upload.interface.ts"
click node_mcpserver "https://github.com/lumizone/postsider/blob/main/apps/mcp/src/server.ts"
click node_mcpclient "https://github.com/lumizone/postsider/blob/main/apps/mcp/src/client.ts"
click node_httpmcp "https://github.com/lumizone/postsider/blob/main/apps/mcp/src/http/server.ts"
click node_sdk "https://github.com/lumizone/postsider/blob/main/apps/sdk/src/index.ts"
click node_auth "https://github.com/lumizone/postsider/blob/main/apps/backend/src/services/auth/auth.service.ts"
click node_mfa "https://github.com/lumizone/postsider/blob/main/apps/backend/src/services/auth/mfa.service.ts"
click node_analytics "https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/analytics.controller.ts"
click node_webhooks "https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/webhooks.controller.ts"
click node_orchestrator "https://github.com/lumizone/postsider/blob/main/apps/orchestrator/src/main.ts"
click node_webhookdelivery "https://github.com/lumizone/postsider/blob/main/apps/orchestrator/src/activities/webhook.delivery.activity.ts"
click node_billing "https://github.com/lumizone/postsider/blob/main/libraries/nestjs-libraries/src/services/polar.service.ts"
click node_bootstrap "https://github.com/lumizone/postsider/blob/main/apps/commands/src/tasks/bootstrap.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_calendar,node_previews,node_channelui toneBlue
class node_postapi,node_approvalapi,node_integrationapi,node_publicapi,node_postdata,node_connectors,node_storage,node_auth,node_mfa,node_analytics,node_webhooks,node_billing toneAmber
class node_mcpserver,node_mcpclient,node_httpmcp,node_sdk toneMint
class node_orchestrator,node_webhookdelivery,node_bootstrap toneRose
class node_human,node_agent toneIndigo
```

## Components

### Planning and publishing

- [Calendar and posts](https://github.com/lumizone/postsider/blob/main/apps/frontend/src/components/calendar.tsx): `apps/frontend/src/components/calendar.tsx`
- [Platform previews](https://github.com/lumizone/postsider/blob/main/apps/frontend/src/components/post-preview/post-preview-panel.tsx): `apps/frontend/src/components/post-preview/post-preview-panel.tsx`
- [Channel UI](https://github.com/lumizone/postsider/blob/main/apps/frontend/src/components/channel-avatar.tsx): `apps/frontend/src/components/channel-avatar.tsx`

### Platform services

- [Post routes](https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/posts.controller.ts): `apps/backend/src/api/routes/posts.controller.ts`
- [Approval routes](https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/approval.controller.ts): `apps/backend/src/api/routes/approval.controller.ts`
- [Channel routes](https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/integrations.controller.ts): `apps/backend/src/api/routes/integrations.controller.ts`
- [Public API](https://github.com/lumizone/postsider/blob/main/apps/backend/src/public-api/routes/v1/public.integrations.controller.ts): `apps/backend/src/public-api/routes/v1/public.integrations.controller.ts`
- [Post services](https://github.com/lumizone/postsider/blob/main/libraries/nestjs-libraries/src/database/prisma/posts/posts.service.ts): `libraries/nestjs-libraries/src/database/prisma/posts/posts.service.ts`
- [Connector registry](https://github.com/lumizone/postsider/blob/main/libraries/nestjs-libraries/src/integrations/integration.manager.ts): `libraries/nestjs-libraries/src/integrations/integration.manager.ts`
- [Media storage](https://github.com/lumizone/postsider/blob/main/libraries/nestjs-libraries/src/upload/upload.interface.ts): `libraries/nestjs-libraries/src/upload/upload.interface.ts`
- [Authentication](https://github.com/lumizone/postsider/blob/main/apps/backend/src/services/auth/auth.service.ts): `apps/backend/src/services/auth/auth.service.ts`
- [MFA service](https://github.com/lumizone/postsider/blob/main/apps/backend/src/services/auth/mfa.service.ts): `apps/backend/src/services/auth/mfa.service.ts`
- [Analytics routes](https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/analytics.controller.ts): `apps/backend/src/api/routes/analytics.controller.ts`
- [Webhook routes](https://github.com/lumizone/postsider/blob/main/apps/backend/src/api/routes/webhooks.controller.ts): `apps/backend/src/api/routes/webhooks.controller.ts`
- [Billing service](https://github.com/lumizone/postsider/blob/main/libraries/nestjs-libraries/src/services/polar.service.ts): `libraries/nestjs-libraries/src/services/polar.service.ts`

### Automation interfaces

- [MCP tools](https://github.com/lumizone/postsider/blob/main/apps/mcp/src/server.ts): `apps/mcp/src/server.ts`
- [API client](https://github.com/lumizone/postsider/blob/main/apps/mcp/src/client.ts): `apps/mcp/src/client.ts`
- [MCP HTTP](https://github.com/lumizone/postsider/blob/main/apps/mcp/src/http/server.ts): `apps/mcp/src/http/server.ts`
- [Node SDK](https://github.com/lumizone/postsider/blob/main/apps/sdk/src/index.ts): `apps/sdk/src/index.ts`

### Background operations

- [Workflow worker](https://github.com/lumizone/postsider/blob/main/apps/orchestrator/src/main.ts): `apps/orchestrator/src/main.ts`
- [Webhook delivery](https://github.com/lumizone/postsider/blob/main/apps/orchestrator/src/activities/webhook.delivery.activity.ts): `apps/orchestrator/src/activities/webhook.delivery.activity.ts`
- [Admin bootstrap](https://github.com/lumizone/postsider/blob/main/apps/commands/src/tasks/bootstrap.admin.ts): `apps/commands/src/tasks/bootstrap.admin.ts`

### Other components

- **Team member**
- **AI agent**

## Connections

- Team member → Calendar and posts: plans content (evidence: `README.md`)
- Calendar and posts → Post routes: submits posts (evidence: `README.md`)
- Team member → Approval routes: reviews drafts (evidence: `README.md`)
- Calendar and posts → Platform previews: previews posts (evidence: `README.md`)
- Calendar and posts → Channel UI: chooses channels (evidence: `README.md`)
- Post routes → Post services: manages posts
- Channel routes → Connector registry: uses connectors (evidence: `apps/backend/src/api/routes/integrations.controller.ts`)
- Team member → Channel routes: connects channels (evidence: `README.md`)
- Post routes → Media storage: handles media
- AI agent → MCP tools: uses tools (evidence: `README.md`)
- MCP tools → API client: calls API client (evidence: `apps/mcp/src/server.ts`)
- MCP HTTP → MCP tools: hosts tools (evidence: `apps/mcp/src/http/server.ts`)
- API client → Public API: calls REST API (evidence: `README.md`)
- Node SDK → Public API: calls REST API (evidence: `README.md`)
- Team member → Authentication: signs in (evidence: `README.md`)
- Authentication → MFA service: supports MFA
- Team member → Analytics routes: reviews analytics (evidence: `README.md`)
- Public API → Webhook routes: manages subscriptions (evidence: `README.md`)
- Webhook delivery → Webhook routes: delivers events
- Workflow worker → Webhook delivery: runs activity
- Team member → Billing service: manages plan
- Team member → Admin bootstrap: creates administrator (evidence: `README.md`)
