Overall Architecture

The Social Media Service is a microservice that interacts with external social media platforms on behalf of Newsmind Stories users. It handles:

• Management of connected social media accounts
• Publishing posts to social platforms (including scheduled publications)
• Media validation / analysis to ensure compliance with platform-specific requirements

All external requests to this service pass through the API Gateway. The service participates in both synchronous (HTTP/REST) and asynchronous (event-driven) flows.

Main operations

The service supports three primary functional areas: account management, post / publication creation and media analysis.

1. Account management (CRUD)

Accounts represent a user's authenticated presence on a specific social media platform.

• Create
  • API Gateway creates an account entry in the Plan API.
  • API Gateway creates the account in the Social Media Service.
  • API Gateway updates the Plan API account with the ID returned by the Social Media Service.
• Read
  • API Gateway fetches all accounts from the Plan API.
  • For each relevant account, API Gateway queries the Social Media Service using the stored external account ID.
  • The Social Media Service returns profile URL, status, etc.
• Update
  • Users can only update the internal description/label of the account.
  • No interaction occurs with the external social platform or the Social Media Service.
• Delete
  • API Gateway deletes the account in the Social Media Service.
  • API Gateway deletes (or marks as deleted) the corresponding entry in the Plan API.

2. Post / publication creation and delivery

Publishing content is an asynchronous, scheduled process involving multiple services.

• Create content object(frontend-initiated)
  • API Gateway creates a Content object in the Plan API.
  • This object holds all post details: type, caption, title, media URLs, thumbnails, etc.
  • No interaction with the Social Media Service at this stage.
• Create publication(frontend-initiated)
  • User requests to publish (immediately or scheduled).
  • API Gateway creates a Publication object in the Plan API.
  • Plan API creates a scheduled task in the Scheduler Service.
  • Scheduler tasks call back to the API Gateway with the publication ID when due.
• Handle publication(scheduler-triggered)
  • Scheduler → API Gateway (callback with publication ID).
  • API Gateway fetches the Publication from the Plan API.
  • Plan API returns the Publication plus the referenced Content object.
  • API Gateway builds a publication request payload and forwards it to the Social Media Service.
  • The Social Media Service creates an internal Post object, publishes a PostCreatedEvent to the message queue, attempts to publish to the external platform, and returns the internal post ID to the API Gateway.
  • API Gateway persists this post ID in the Publication object (via Plan API).
• Publication outcome / status update
  • The Social Media Service monitors delivery status (success, failed, partial, etc.).
  • Regardless of the outcome, the Social Media Service calls the API Gateway with the publication ID and the final delivery status.
  • API Gateway updates deliveryStatus on the Publication via the Plan API and creates a user notification via the Notification Service.

This flow ensures reliable, trackable and auditable publishing even for delayed/scheduled posts.

3. Media analysis and validation

Many platforms enforce strict requirements on media (size, aspect ratio, duration, format, etc.).

• The frontend calls a dedicated endpoint on the Social Media Service before allowing upload/publication.
• Endpoint: POST /media/validate (or similar).
• Input: media URL + target platform/provider.
• The Social Media Service delegates analysis to the Media Analysis Service, sending the media URL and receiving technical metadata (dimensions, duration, file size, MIME type, etc.).
• The Social Media Service then loads platform-specific requirements from a local configuration file, compares the metadata against the rules, and returns an array of violated constraints (e.g. "aspect_ratio_out_of_range", "duration_too_long") or an empty array if compliant.

This check happens early in the content creation flow to prevent invalid submissions.

Deployment and configuration requirements

For correct operation, the following services must be available and properly configured.

Plan API

Required for all operations. Connected to the API Gateway via application properties.

# API Gateway Service
DIRECT_PLANAPI_SERVICE: string
DIRECT_PLANAPI_PATH: string
DIRECT_PLANAPI_HOST: string
DIRECT_PLANAPI_PORT: string
DIRECT_PLANAPI_SCHEME: string

Notification Service

Required for publication status notifications. Connected indirectly to the API Gateway via Redis Streams.

# API Gateway Service
MESSAGING_HOST: string
MESSAGING_PORT: string
NOTIFICATION_TOPIC: string

# Social Media Service
NOTIFICATION_GATEWAY_BASE_URL: string
NOTIFICATION_ENDPOINT: string

Scheduler Service

Required for scheduled publications. Connected to the Plan API via application properties.

# Plan API Service
SCHEDULER_SERVICE: string
SCHEDULER_PATH: string
SCHEDULER_HOST: string
SCHEDULER_PORT: string
SCHEDULER_SCHEME: string

Media Analysis Service

Required for media validation. Connected to the Social Media Service via application properties.

# Social Media Service
MEDIA_ANALYZER_BASE_URL: string

Message queue

Required for PostCreatedEvent (and possibly others). Currently in-memory in the Social Media Service.

Special case: authentication for scheduler-triggered calls

Since the implementation of the object history feature, some Plan API endpoints are protected and every incoming request for them must be authenticated. The publication endpoints are among them. Since the social media posting process is asynchronous and driven by services rather than users, a dedicated system user was created in the authorization server for the social media posting process and configured in the API Gateway. When handling scheduler callbacks, the API Gateway authenticates as this system user and forwards the X-User-Token (or equivalent) to the Plan API for protected routes.

# API Gateway
SERVICE_ACCOUNT_KEYCLOAK_TOKEN_URL: string
SOCIAL_MEDIA_AUTH_CLIENT: string
SOCIAL_MEDIA_AUTH_SECRET: string

Asset handling for social media publications

In Newsmind Stories, all user-uploaded assets (images, videos, thumbnails, etc.) are stored private by default in a dedicated S3 bucket. This ensures they remain inaccessible from the public internet and are only available to authenticated users within the platform.

When a user schedules or publishes content that includes these assets on a social media platform, the Social Media Service must make the relevant assets accessible to the external provider (e.g. during upload to Instagram, TikTok, X, etc.).

To achieve this securely and efficiently:

• The Social Media Service moves the required asset(s) from the private bucket to a dedicated public bucket.
• The public bucket is configured with public read access (via bucket policy or object ACLs), allowing social media platforms to fetch the media during the publication process.

The Social Media Service must have access to both S3 buckets:

# Social Media Service
S3_HOSTNAME: string
S3_USERNAME: string
S3_PASSWORD: string
S3_BUCKET_NAME: string
S3_SERVICE_PREFIX: string
S3_REGION: string

SOCIAL_MEDIA_S3_HOSTNAME: string
SOCIAL_MEDIA_S3_USERNAME: string
SOCIAL_MEDIA_S3_PASSWORD: string
SOCIAL_MEDIA_S3_BUCKET_NAME: string
SOCIAL_MEDIA_S3_SERVICE_PREFIX: string
SOCIAL_MEDIA_S3_REGION: string

Requirements for account connection

The management of external social media accounts is done via two main concepts: Account and Profile. The Account represents the user's actual external account with the provider. A Profile represents how external providers allow users to do different things with the same account.

To use the Social Media Service to publish, every user needs an account with the external provider they want to use, as well as at least one profile. Every provider has its own definition of what an account and a profile are.