$ show gitroomhq/postiz-app
Postiz is a full-stack, open-source social media scheduling and publishing platform that supports 30+ platforms (Instagram, TikTok, LinkedIn, YouTube, X, Facebook, etc.). The system is built as a pnpm monorepo with four main applications: a Next.js frontend (App Router), a NestJS backend REST API, a Temporal-based workflow orchestrator for reliable post publishing and token refresh, and a Chrome extension for cookie-based authentication. It also includes a CLI app, a public SDK (@postiz/node), and a shared libraries layer for business logic, database access (Prisma + PostgreSQL), and integrations. Key architectural patterns include an abstract social provider base class (SocialAbstract) that all platform integrations extend, a Temporal v1.8+ workflow engine with versioned posting workflows (v1.0.1 through v1.0.8), an upload factory abstracting local and Cloudflare storage, an MCP server for AI agent tools (scheduling, content generation via LangGraph), a plug/auto-reply system, and a short-link abstraction with multiple providers. The frontend uses Zustand for state management, SWR for data fetching, CopilotKit for AI textarea integration, and Mantine/Tailwind for UI. The system handles OAuth flows, subscription billing via Stripe, team collaboration, webhooks, and admin monitoring. The codebase demonstrates strong engineering with reusable abstractions for social integrations, storage, email, and short-linking, though it carries some technical debt from organic growth (multiple workflow versions, hardcoded strings, and suppressed TypeScript strictness).
The LLM identified 5 files worth highlighting for reuse:
Base class for all social media platform integrations. Provides SSRF-safe HTTP fetch, image dimension validation via sharp, streamed media uploads, and a standardized error classification system (refresh-token, bad-body, retry, disconnect). Each provider (Instagram, TikTok, LinkedIn, etc.) extends this class to implement post(), postPending(), checkPostStatus(), finalizePost(), and analytics(). This pattern is highly reusable for any multi-platform API integration system; extracting it requires minimal adaptation of the fetch and error handling logic.
Factory function that returns a storage provider instance (LocalStorage or CloudflareR2) based on environment configuration (process.env.STORAGE_PROVIDER). The underlying IUploadProvider interface defines put(), del(), getUrl(), etc. This decouples the application from a specific storage backend, making it easy to add new providers (e.g., S3, GCS). The pattern can be extracted to any project requiring pluggable file storage.
Central registry of tools exposed to the AI agent via the MCP server. Each tool is defined using the @Tool decorator with a name, description, and JSON Schema for parameters. Tools cover post scheduling, integration listing, group retrieval, and video generation. This pattern demonstrates a clean separation between business logic and AI interaction, and can be reused for building custom MCP servers for other domains.
Service that delegates to one of several short-link providers (Dub, Short.io, Kutt, LinkDrip) based on the configured provider name. All providers implement the ShortLinking interface. This pattern is a clean example of the strategy pattern for external service integration, easily extractable for any project that needs pluggable third-party dependencies.
Core Temporal activity that orchestrates posting a single piece of content across multiple social platforms. It handles media uploads, token refresh, plug (auto-reply) execution, and webhook notifications. The activity uses a sophisticated error classification that distinguishes between retryable, bad-body, token-expired, and connectivity errors, enabling the workflow to make intelligent decisions (re-queue, skip, refresh token). This pattern is a reference for building robust, stateful background job systems with Temporal.