# mosinatet/communication-specialist-ai architecture

> Architecture diagram of the GitHub repository mosinatet/communication-specialist-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mosinatet/communication-specialist-ai
- Repository: https://github.com/mosinatet/communication-specialist-ai

## Overview

##### Project Type and Purpose
- This is a full-stack social media management platform (“SocialMediaAI”) combining a FastAPI backend and a React/TypeScript frontend.
- It provides AI-powered content generation (via Google Generative AI), post scheduling (APScheduler), multi-platform posting (Twitter, LinkedIn, Dev.to), and analytics.

##### File Structure
- Top-level:
- backend/ – FastAPI application, models, scheduler, social API integrations, database setup, tests.
- frontend/ – Vite-powered React/TypeScript SPA, components, pages, services.
- .github/workflows – CI pipeline.
- Key config files: backend/requirements.txt, frontend/package.json, environment templates (.env), Dockerfiles (if added later).
- Tests in backend/test exercise API endpoints, database, and social integrations.

##### README Insights
- Tech stack clearly splits responsibilities: FastAPI + SQLAlchemy + APScheduler + external AI & social APIs on the backend; React + Vite + Tailwind CSS on the frontend.

a. Frontend Hosting
- A static web host (e.g., Vercel, Netlify, S3+CloudFront) serving the React SPA built by Vite.
b. Backend API Server
- FastAPI app running under Uvicorn/Gunicorn on a compute resource (e.g., AWS EC2, ECS Fargate, Azure App Service, GKE).
c. Database
- Relational DB (PostgreSQL/MySQL) hosted on a managed service (AWS RDS, Azure DB, Cloud SQL).
d. Scheduler
- APScheduler job runner, either embedded in the same backend container or in a separate worker container/cron service.
e. External Services
- Google Generative AI endpoint
- Twitter, LinkedIn, Dev.to REST APIs
f. CI/CD Pipeline
- GitHub Actions workflow that builds, tests, and deploys frontend & backend.

##### Relationships & Interactions
1. User Browser ←→ Frontend (HTTPS)
2. Frontend → Backend API (HTTPS REST)
3. Backend → Database (SQL)
4. Backend → Google Generative AI (HTTPS)
5. Backend → Social Media APIs (HTTPS)
6. Scheduler triggers backend tasks → External & Database
7. CI/CD → Deploy frontend artifact to CDN, backend Docker image to container registry & host

##### Architectural Patterns & Design Principles
- Monolithic backend with modular code (app/, models, scheduler, social_media_platforms).
- Single-page application (SPA) frontend served statically.
- Externalized configuration via environment variables.
- Layered: presentation (frontend), API, business logic (ai_agent.py, scheduler.py), data access (database.py, models.py).
- Reusable service clients for each social platform.

## Diagram (Mermaid)

```mermaid
flowchart TD
    direction TB

    %% External Tier
    subgraph "External Tier"
        direction TB
        AI["Google Generative AI"]:::external
        TW["Twitter API"]:::external
        LI["LinkedIn API"]:::external
        DEV["Dev.to API"]:::external
    end

    %% Data Tier
    subgraph "Data Tier"
        direction TB
        DB["PostgreSQL Database\n(5432/TCP)"]:::database
    end

    %% Frontend Hosting
    subgraph "Presentation Tier\n(CDN / Static Host)" 
        direction TB
        User["User Browser"]:::frontend
        CDN["CDN / Static Host"]:::frontend
        App["React SPA"]:::frontend
    end

    %% Application Tier
    subgraph "Application Tier\n(Application Environment)"
        direction TB
        ALB["Load Balancer / API Gateway"]:::backend
        API["FastAPI Service"]:::backend
        SCH["Scheduler\n(APScheduler)"]:::backend
    end

    %% CI/CD
    CI["GitHub Actions\nCI/CD Pipeline"]:::cicd

    %% Connections
    User -->|"HTTPS"| CDN
    CDN -->|"Serves SPA"| App
    App -->|"HTTPS REST"| ALB
    ALB -->|"HTTPS REST"| API
    SCH -->|"Trigger Jobs"| API

    API -->|"SQL"| DB
    SCH -->|"SQL"| DB

    API -->|"HTTPS"| AI
    API -->|"HTTPS"| TW
    API -->|"HTTPS"| LI
    API -->|"HTTPS"| DEV

    CI -->|"Deploy SPA"| CDN
    CI -->|"Build & Deploy"| API
    CI -->|"Run Tests"| API

    %% Click Events
    click App "https://github.com/mosinatet/communication-specialist-ai/tree/master/frontend/"
    click CDN "https://github.com/mosinatet/communication-specialist-ai/blob/master/frontend/src/main.tsx"
    click API "https://github.com/mosinatet/communication-specialist-ai/blob/master/backend/app/main.py"
    click SCH "https://github.com/mosinatet/communication-specialist-ai/blob/master/backend/app/scheduler.py"
    click DB "https://github.com/mosinatet/communication-specialist-ai/blob/master/backend/app/database.py"
    click CI "https://github.com/mosinatet/communication-specialist-ai/blob/master/.github/workflows/master_et-ci-dev-csai-ui.yml"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#0288d1,stroke-width:1px;
    classDef backend fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px;
    classDef database fill:#ffe0b2,stroke:#f57c00,stroke-width:1px;
    classDef external fill:#eceff1,stroke:#546e7a,stroke-width:1px;
    classDef cicd fill:#f3e5f5,stroke:#6a1b9a,stroke-width:1px;
```
