🏗️ Arquitetura multi-plataforma

Cada rede social tem uma API diferente: X usa OAuth 2.0 PKCE, LinkedIn pede UGC posts, Instagram exige container ID. Sem abstração, o código vira um switch gigante. O padrão Adapter resolve isso: uma classe por rede, todas implementando a mesma interface.

O resto da aplicação fala com a interface, não com a API específica. Adicionar TikTok amanhã = criar TikTokProvider e registrar no factory — zero mudança no agendador, na fila ou no frontend.

// Interface comum — contrato que TODA rede implementa
export interface SocialProvider {
  readonly platform: 'x' | 'linkedin' | 'instagram' | 'facebook' | 'tiktok';

  authenticate(code: string): Promise<AuthResult>;
  refreshToken(refreshToken: string): Promise<AuthResult>;
  post(account: SocialAccount, payload: PostPayload): Promise<PostResult>;
  delete(account: SocialAccount, externalId: string): Promise<void>;
  getMetrics(account: SocialAccount, externalId: string): Promise<Metrics>;
}

// Implementação concreta — uma por rede
export class XProvider implements SocialProvider {
  readonly platform = 'x' as const;

  async authenticate(code: string) { /* OAuth 2.0 PKCE */ }
  async post(account, payload) {
    // chama POST /2/tweets com bearer token
  }
  // ...
}

// Factory escolhe o provider certo em runtime
export function getProvider(platform: string): SocialProvider {
  return providers[platform]; // { x: new XProvider(), linkedin: ... }
}

Conceitos-chave

Publicar post não é uma chamada síncrona. O usuário aperta "agendar para amanhã 9h" e o sistema precisa lembrar de publicar, tentar de novo se falhar, e não derrubar a app quando a API da rede estiver lenta. Filas resolvem os três.

BullMQ (Redis) cobre 95% dos casos: delay nativo, retry com backoff exponencial, jobs agendados via cron. Temporal entra quando você precisa de workflows duradouros (ex: thread no X com 10 tweets sequenciais com falha parcial).

// Agendar publicação para horário futuro
await postQueue.add(
  'publish-post',
  { postId: '42', target: 'linkedin' },
  {
    delay: scheduledAt.getTime() - Date.now(), // ms até disparar
    attempts: 5,
    backoff: { type: 'exponential', delay: 30_000 }, // 30s, 60s, 120s...
    removeOnComplete: { age: 86_400 }, // mantém logs 24h
  }
);

// Worker que processa
new Worker('post-queue', async (job) => {
  const provider = getProvider(job.data.target);
  return await provider.post(account, payload);
}, { concurrency: 4 });

Conceitos-chave

Quase nenhuma API aceita imagem em base64. X, LinkedIn e Instagram exigem URL pública ou upload prévio com multipart. Resultado: você precisa de um object storage antes de chamar o provider. Sem isso, qualquer post com foto falha.

O fluxo padrão é: usuário sobe arquivo → backend gera signed URL → frontend faz PUT direto no S3/R2/Cloudinary → backend salva a URL final no Post. Nada de proxy pela aplicação — desperdiça banda e timeout.

// Backend gera signed URL — válida por 5 min, só PUT
const command = new PutObjectCommand({
  Bucket: 'mkblogs-media',
  Key: `${userId}/${nanoid()}.jpg`,
  ContentType: 'image/jpeg',
});
const uploadUrl = await getSignedUrl(s3, command, { expiresIn: 300 });

// Frontend faz upload direto, sem passar pelo backend
await fetch(uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'image/jpeg' },
  body: file,
});

// Depois, ao postar:
// - X: media_id obtido via /1.1/media/upload.json
// - LinkedIn: registerUpload + PUT no asset URL
// - Instagram: image_url DEVE ser HTTPS público acessível por Meta

Conceitos-chave

A modelagem certa torna features futuras (cross-post, analytics, rascunhos) triviais. A errada te força a refatorar tudo no segundo mês. Cinco tabelas formam o núcleo: User, SocialAccount, Post, PostTarget e Media.

A separação Post (conteúdo lógico) × PostTarget (publicação por rede) é o que permite um post → várias redes com status independente em cada uma.

// schema.prisma — núcleo da modelagem
model User {
  id        String   @id @default(cuid())
  email     String   @unique
  accounts  SocialAccount[]
  posts     Post[]
}

model SocialAccount {
  id           String   @id @default(cuid())
  userId       String
  platform     String   // 'x', 'linkedin', 'instagram'...
  externalId   String   // ID da conta na rede
  accessToken  String   // criptografado em rest
  refreshToken String?
  expiresAt    DateTime?
  user         User     @relation(fields: [userId], references: [id])
  targets      PostTarget[]
  @@unique([userId, platform, externalId])
}

model Post {
  id          String   @id @default(cuid())
  userId      String
  content     String   // markdown / texto base
  scheduledAt DateTime
  status      String   // 'draft' | 'scheduled' | 'partial' | 'done' | 'failed'
  user        User     @relation(fields: [userId], references: [id])
  targets     PostTarget[]
  media       Media[]
}

model PostTarget {
  id              String   @id @default(cuid())
  postId          String
  socialAccountId String
  status          String   // 'pending' | 'publishing' | 'published' | 'failed'
  externalPostId  String?  // ID retornado pela rede após publicar
  error           String?
  publishedAt     DateTime?
  post            Post @relation(fields: [postId], references: [id])
  account         SocialAccount @relation(fields: [socialAccountId], references: [id])
}

model Media {
  id     String @id @default(cuid())
  postId String
  url    String // S3/R2/Cloudinary
  type   String // 'image' | 'video'
  post   Post   @relation(fields: [postId], references: [id])
}

Conceitos-chave

O frontend é o lugar onde o usuário sente se a ferramenta é boa. Quatro componentes definem a experiência: editor com contagem de chars por rede, preview fiel ao look de cada plataforma, calendário visual e drag-drop para reagendar sem clicar em menu.

Conceitos-chave

Algumas redes (Meta principalmente) confirmam publicação de forma assíncrona: você manda o post, recebe um ID temporário, e só algum tempo depois um webhook avisa "publicou OK" ou "rejeitou por política de conteúdo". Sem expor um endpoint de webhook, você fica adivinhando status.

O fluxo é: rede social → POST no seu /webhooks/instagram com payload assinado → você valida assinatura HMAC → atualiza PostTarget.status e notifica o frontend via WebSocket/SSE.

// Endpoint público para receber callbacks
app.post('/webhooks/instagram', async (req, res) => {
  // 1. Validar assinatura HMAC (NÃO confiar no payload sem isso)
  const sig = req.headers['x-hub-signature-256'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.META_APP_SECRET)
    .update(req.rawBody)
    .digest('hex');
  if (sig !== expected) return res.status(401).end();

  // 2. Processar evento
  for (const entry of req.body.entry) {
    await handleEvent(entry); // atualiza PostTarget
  }

  // 3. Responder 200 RÁPIDO — Meta retenta se demorar >5s
  res.status(200).end();
});

Conceitos-chave