# harshrajeevsingh/postiz-app architecture

> Architecture diagram of the GitHub repository harshrajeevsingh/postiz-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harshrajeevsingh/postiz-app
- Repository: https://github.com/harshrajeevsingh/postiz-app

## Overview

Based on our analysis of the file tree and README, this is a full-stack, monorepo-based application built with NX that combines a NextJS frontend with a NestJS backend. It also includes several specialized apps (commands, cron jobs, workers) as well as shared libraries (both for NestJS and React) that encapsulate core business logic, integrations, and utilities. In short, Postiz is an AI-driven social media scheduling and analytics tool with multiple subsystems handling APIs, job scheduling, real-time notifications, email communications, and integrations with external social media networks.

##### Main Components
- Frontend:
- The NextJS application found in apps/frontend, responsible for the user interface.
- Includes layout, both site and auth routes, and components for analytics, billing, messaging, etc.
- Backend:
- The NestJS API application (apps/backend) handling various REST API endpoints such as authentication, billing, messaging, analytics, and external integrations.
- Contains middleware, services, and controllers to serve API requests.
- Background Jobs and Services:
- Commands (apps/commands) – CLI tasks or one-off scripts.
- Cron (apps/cron) – scheduled tasks for periodic jobs (e.g., syncing trending data).
- Workers (apps/workers) – process background tasks and integration-related controllers.
- Libraries:
- NestJS Shared Libraries (libraries/nestjs-libraries) – abstractions for database access (Prisma repositories/services), integrations (social providers, queue management with BullMQ), authentication, and other central service logic.
- React Shared Libraries (libraries/react-shared-libraries) – common UI components and helpers used by the frontend.
- Other helper libraries and plugins that offer reusable functionality (helpers, plugins, etc.).
- External Services and Infrastructure:
- Integration with PostgreSQL using Prisma.
- Redis and BullMQ for queuing and background task processing.
- Email service integration with Resend for notifications.
- Docker-related files indicate containerized deployments (including Docker, docker-compose, and supervision scripts).
- Development and CI/CD Infrastructure:
- Dev containers, GitHub workflows, ESLint, Prettier, and other configuration files to enforce code quality and continuous integration.

##### Relationships and Interactions
- Frontend interacts with the backend via API calls. The NextJS app will invoke endpoints for actions like authentication, scheduling posts, analytics retrieval, etc.
- The backend (NestJS) orchestrates business logic. It communicates with various databases (via Prisma) and triggers background jobs through Redis/BullMQ.
- Commands, cron jobs, and workers are auxiliary applications that run tasks asynchronously or at scheduled intervals. These should be represented as separate services that interact with the backend and shared libraries.
- Shared libraries provide a common layer that wraps integration logic (social media APIs, email delivery, etc.) and common utilities used across different apps.

##### Architectural Patterns and Design Principles
- Modular Monorepo: The NX monorepo architecture allows for isolating responsibilities (frontend, backend, commands, cron, workers) while still sharing common code through libraries.
- API Gateway/RESTful API: The backend follows a clear structure with route-based controllers and middleware (e.g. authentication, permissions) to handle client requests.
- Service-Based/Layered Architecture: Use cases are separated into controllers, services, data access layers (via Prisma), and integration modules.
- Asynchronous Processing: Redis and BullMQ are used to decouple background job processing from the immediate request lifecycle.
- Containerization: Numerous Docker configurations for development and deployment to ensure environment consistency.

##### Relevant Technologies, Frameworks, and Libraries
- Frontend: NextJS, React, Tailwind, and custom React shared libraries.
- Backend: NestJS, Express (under the hood), Prisma (for PostgreSQL), Redis, BullMQ, and Resend for emails.
- Build and Monorepo Tools: NX, Webpack (configuration files in each app), ESLint, Prettier.
- Other Interactions: Docker, GitHub Actions workflows (for CI/CD), and integration with third-party social media APIs.

##### Overall Process
- Divide sections for the frontend, backend, and auxiliary services.
- Involving external services (database, Redis, etc.) and connections.
- Shared libraries as underlying “common modules” influencing both backend and frontend.
- Clarity with labels and comments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        F1["NextJS Frontend"]:::frontend
        SReact["React Shared Libraries"]:::shared
        F1 -->|"usesUI"| SReact
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B1["NestJS API"]:::backend
        SNest["NestJS Shared Libraries"]:::shared
        SHelper["Helper/Utility Libraries"]:::shared
        DB["Prisma Database Layer"]:::infra
        EMAIL["External Email Service – Resend"]:::infra
        F1 -->|"APICall"| B1
        B1 -->|"usesLogic"| SNest
        B1 -->|"utilizes"| SHelper
        B1 -->|"queries"| DB
        B1 -->|"sendsEmail"| EMAIL
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        CMD["Commands Service"]:::auxiliary
        CRON["Cron Scheduler"]:::auxiliary
        WRK["Worker Service"]:::auxiliary
        SNest -->|"CLI_Task"| CMD
        SNest -->|"Scheduled_Task"| CRON
    end

    %% Background Job Processing Flow
    B1 -->|"enqueuesJob"| REDIS["Redis Integration"]:::infra
    REDIS -->|"queueMgmt"| BULL["BullMQ Integration"]:::infra
    BULL -->|"processesJob"| WRK

    %% Infrastructure Components
    subgraph "Infrastructure"
        DOCKER["Docker & Containerization"]:::infra
        CICD["CI/CD & Dev Infrastructure"]:::infra
        DOCKER --- B1
        DOCKER --- F1
        CICD --- B1
        CICD --- F1
    end

    %% Click Events
    click F1 "https://github.com/harshrajeevsingh/postiz-app/tree/main/apps/frontend"
    click B1 "https://github.com/harshrajeevsingh/postiz-app/tree/main/apps/backend"
    click CMD "https://github.com/harshrajeevsingh/postiz-app/tree/main/apps/commands"
    click CRON "https://github.com/harshrajeevsingh/postiz-app/tree/main/apps/cron"
    click WRK "https://github.com/harshrajeevsingh/postiz-app/tree/main/apps/workers"
    click SNest "https://github.com/harshrajeevsingh/postiz-app/tree/main/libraries/nestjs-libraries"
    click SReact "https://github.com/harshrajeevsingh/postiz-app/tree/main/libraries/react-shared-libraries"
    click SHelper "https://github.com/harshrajeevsingh/postiz-app/tree/main/libraries/helpers"
    click DB "https://github.com/harshrajeevsingh/postiz-app/tree/main/libraries/nestjs-libraries/src/database/prisma"
    click REDIS "https://github.com/harshrajeevsingh/postiz-app/tree/main/libraries/nestjs-libraries/src/redis"
    click BULL "https://github.com/harshrajeevsingh/postiz-app/tree/main/libraries/nestjs-libraries/src/bull-mq-transport-new"
    click DOCKER "https://github.com/harshrajeevsingh/postiz-app/blob/main/Dockerfile.dev"
    click CICD "https://github.com/harshrajeevsingh/postiz-app/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#A9D0F5,stroke:#1F618D,stroke-width:2px;
    classDef backend fill:#ABEBC6,stroke:#1E8449,stroke-width:2px;
    classDef auxiliary fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef shared fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef infra fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
