# prince5723/social-medi-bot architecture

> Architecture diagram of the GitHub repository prince5723/social-medi-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prince5723/social-medi-bot
- Repository: https://github.com/prince5723/social-medi-bot

## Overview

##### Project Type and Purpose
- This is a backend service (Node.js + Express) for social media automation.
- It exposes a REST-style API to clients for user management, scheduling posts, automating interactions, trend monitoring, and reporting.
- It integrates with external services (Twitter and LinkedIn APIs), uses MongoDB for data storage, Redis/Bull for job queues, JWT for auth, and Zod for validation.

##### File Structure
- Top-level files:
- .env.example (environment variables template)
- package.json / package-lock.json (dependencies)
- README.md (project overview)
- src/
- config/ (db.js, logger.js)
- controllers/ (HTTP request handlers by resource)
- middlewares/ (authentication, validation, error handling)
- models/ (Mongoose schemas)
- routes/ (Express routing by resource)
- services/ (business logic, including social media integrations and scheduler)
– social/ (LinkedIn and Twitter service implementations)
- utils/ (JWT utilities)
- app.js (Express app setup)
- server.js (HTTP server startup)
- External integration points: OAuth flows under social-auth.controller + social services.
- Queue system: scheduler.service + Bull/Redis (not explicit in file tree but mentioned in README).

##### Key Insights from README
- Features: scheduled posting, interaction automation, trend monitoring, analytics.
- Architecture: layered (controllers → services → models).
- Tech stack and dependencies: Express, Mongoose, Redis/Bull, Winston, Zod, JWT, OAuth 2.0, Swagger.

##### Main Components
a. API Gateway / Client Layer
- External clients (Web front-ends, Postman, mobile apps) invoking HTTP requests.
b. Express Application Layer
- HTTP server (server.js)
- app.js: mounts middlewares, routes, Swagger docs
- Middlewares: authentication (JWT), validation (Zod), error handling, logging.
c. Controller Layer
- auth.controller, user.controller, post.controller, interaction.controller, trend.controller, report.controller, social-auth.controller.
d. Service Layer
- Core services: interaction.service, scheduler.service, social-auth.service
- Social integrations: linkedin.service, twitter.service
- Business rules, queue producers (scheduler schedules jobs via Bull)
e. Data Layer
- Models (Mongoose schemas) mapping to MongoDB collections
- db.js for connection pooling and configuration
f. Queue System
- Redis instance running Bull queues
- Background workers (could be the same Node process or separate processes) consuming scheduled jobs and invoking social services
g. External Dependencies
- MongoDB (persistent storage)
- Redis (job queue store)
- Twitter API, LinkedIn API (OAuth2 flows, REST endpoints)
h. Utility Components
- JWT utility (token generation/verification)
- Logger (Winston)

##### Relationships and Data Flow
- API Gateway → Middlewares → Controller
- Controller → Service → Model (for DB operations)
- Service → Queue (via Bull/Redis) for scheduled jobs
- Worker → Service → External API (Twitter/LinkedIn)
- Service → Model → Database (MongoDB)
- Service → Report Generation → Model → Database
- Controller → Response → Client

##### Architectural Patterns and Principles
- Layered architecture: clear separation of concerns (routing, validation, business logic, data access).
- Modularization by domain: each resource has its own controller, service, and routes.
- Asynchronous background processing: job queue for scheduled tasks.
- Security: JWT auth at middleware level, OAuth2 for social integrations.
- Configuration management: environment variables loaded at startup.
- Validation: Zod schemas in middleware layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Clients["External Clients<br/>(Web, Mobile, Postman)"]:::external
    end

    %% API Layer
    subgraph "API Gateway & Server" 
        direction TB
        Server["HTTP Server<br/>(server.js)"]:::internal
        App["Express App<br/>(app.js)"]:::internal
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        direction TB
        DBConfig["DB Config<br/>(db.js)"]:::db
        Logger["Logger<br/>(logger.js)"]:::internal
        JWTUtil["JWT Utility<br/>(jwt.js)"]:::util
    end

    %% Middleware
    subgraph "Middleware Layer"
        direction TB
        AuthMW["Auth Middleware<br/>(auth.middleware.js)"]:::internal
        ValidateMW["Validation Middleware<br/>(validate.middleware.js)"]:::internal
        ErrorMW["Error Handling Middleware<br/>(error.middleware.js)"]:::internal
    end

    %% Controllers
    subgraph "Controller Layer"
        direction TB
        AuthCtrl["Auth Controller"]:::internal
        UserCtrl["User Controller"]:::internal
        PostCtrl["Post Controller"]:::internal
        InteractionCtrl["Interaction Controller"]:::internal
        TrendCtrl["Trend Controller"]:::internal
        ReportCtrl["Report Controller"]:::internal
        SocialAuthCtrl["Social-Auth Controller"]:::internal
    end

    %% Services
    subgraph "Service Layer"
        direction TB
        InteractionSvc["Interaction Service"]:::internal
        SchedulerSvc["Scheduler Service"]:::internal
        SocialAuthSvc["Social-Auth Service"]:::internal
        subgraph "Social Integration"
            direction TB
            LinkedInSvc["LinkedIn Service"]:::external
            TwitterSvc["Twitter Service"]:::external
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        UserModel["User Model"]:::db
        ScheduleModel["Schedule Model"]:::db
        InteractionModel["Interaction Model"]:::db
        TrendModel["Trend Model"]:::db
        ReportModel["Report Model"]:::db
    end

    %% Queue System
    subgraph "Queue System"
        direction TB
        Redis["Redis (Bull)"]:::queue
        Worker["Background Worker"]:::internal
    end

    %% External APIs
    subgraph "External APIs"
        direction TB
        TwitterAPI["Twitter API"]:::external
        LinkedInAPI["LinkedIn API"]:::external
    end

    %% Flows
    Clients -->|"HTTP Request"| Server
    Server --> App
    App --> AuthMW
    AuthMW --> ValidateMW
    ValidateMW --> ErrorMW
    ErrorMW --> AuthCtrl
    ErrorMW --> UserCtrl
    ErrorMW --> PostCtrl
    ErrorMW --> InteractionCtrl
    ErrorMW --> TrendCtrl
    ErrorMW --> ReportCtrl
    ErrorMW --> SocialAuthCtrl

    AuthCtrl --> AuthSvc["Auth Service"]:::internal
    UserCtrl --> InteractionSvc
    PostCtrl --> SchedulerSvc
    InteractionCtrl --> InteractionSvc
    TrendCtrl --> InteractionSvc
    ReportCtrl --> InteractionSvc
    SocialAuthCtrl --> SocialAuthSvc

    %% Services to Social Integration and Queue
    SchedulerSvc -->|enqueue job| Redis
    Redis -->|dispatch job| Worker
    Worker -->|execute job| LinkedInSvc
    Worker -->|execute job| TwitterSvc

    InteractionSvc -->|CRUD| UserModel
    InteractionSvc -->|CRUD| ScheduleModel
    InteractionSvc -->|CRUD| InteractionModel
    InteractionSvc -->|CRUD| TrendModel
    InteractionSvc -->|CRUD| ReportModel

    %% Controllers direct DB
    AuthSvc --> UserModel

    %% External API calls for OAuth
    SocialAuthSvc -->|OAuth flow| TwitterAPI
    SocialAuthSvc -->|OAuth flow| LinkedInAPI
    TwitterAPI -->|callback| SocialAuthCtrl
    LinkedInAPI -->|callback| SocialAuthCtrl

    %% Config & Util usages
    App --> DBConfig
    App --> Logger
    AuthMW --> JWTUtil

    %% Click Events
    click App "https://github.com/prince5723/social-medi-bot/blob/main/src/app.js"
    click Server "https://github.com/prince5723/social-medi-bot/blob/main/src/server.js"
    click DBConfig "https://github.com/prince5723/social-medi-bot/blob/main/src/config/db.js"
    click Logger "https://github.com/prince5723/social-medi-bot/blob/main/src/config/logger.js"
    click AuthMW "https://github.com/prince5723/social-medi-bot/blob/main/src/middlewares/auth.middleware.js"
    click ValidateMW "https://github.com/prince5723/social-medi-bot/blob/main/src/middlewares/validate.middleware.js"
    click ErrorMW "https://github.com/prince5723/social-medi-bot/blob/main/src/middlewares/error.middleware.js"
    click AuthCtrl "https://github.com/prince5723/social-medi-bot/blob/main/src/controllers/auth.controller.js"
    click UserCtrl "https://github.com/prince5723/social-medi-bot/blob/main/src/controllers/user.controller.js"
    click PostCtrl "https://github.com/prince5723/social-medi-bot/blob/main/src/controllers/post.controller.js"
    click InteractionCtrl "https://github.com/prince5723/social-medi-bot/blob/main/src/controllers/interaction.controller.js"
    click TrendCtrl "https://github.com/prince5723/social-medi-bot/blob/main/src/controllers/trend.controller.js"
    click ReportCtrl "https://github.com/prince5723/social-medi-bot/blob/main/src/controllers/report.controller.js"
    click SocialAuthCtrl "https://github.com/prince5723/social-medi-bot/blob/main/src/controllers/social-auth.controller.js"
    click InteractionSvc "https://github.com/prince5723/social-medi-bot/blob/main/src/services/interaction.service.js"
    click SchedulerSvc "https://github.com/prince5723/social-medi-bot/blob/main/src/services/scheduler.service.js"
    click SocialAuthSvc "https://github.com/prince5723/social-medi-bot/blob/main/src/services/social-auth.service.js"
    click LinkedInSvc "https://github.com/prince5723/social-medi-bot/blob/main/src/services/social/linkedin.service.js"
    click TwitterSvc "https://github.com/prince5723/social-medi-bot/blob/main/src/services/social/twitter.service.js"
    click UserModel "https://github.com/prince5723/social-medi-bot/blob/main/src/models/user.model.js"
    click ScheduleModel "https://github.com/prince5723/social-medi-bot/blob/main/src/models/schedule.model.js"
    click InteractionModel "https://github.com/prince5723/social-medi-bot/blob/main/src/models/interaction.model.js"
    click TrendModel "https://github.com/prince5723/social-medi-bot/blob/main/src/models/trend.model.js"
    click ReportModel "https://github.com/prince5723/social-medi-bot/blob/main/src/models/report.model.js"
    click JWTUtil "https://github.com/prince5723/social-medi-bot/blob/main/src/utils/jwt.js"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366D6,stroke-width:1px;
    classDef db fill:#DFFFE0,stroke:#33A653,stroke-width:1px,stroke-dasharray: 5 5;
    classDef queue fill:#FFE4B5,stroke:#D2691E,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#636363,stroke-width:1px;
    classDef util fill:#F0E0FF,stroke:#8A2BE2,stroke-width:1px;
```
