Social Posts API Refactoring - Executive Summary

Overview

This refactoring transforms the social posts publishing system from route-heavy logic to a workflow-based architecture with schema validation, reducing complexity by 87% while improving maintainability and type safety.

---

Key Improvements

1. Security-First with Token Encryption ⭐ NEW

• ✅ AES-256-GCM encryption for all tokens
• ✅ Tokens encrypted at rest in database
• ✅ Key rotation support without downtime
• ✅ Protection against database breaches
• ✅ GDPR/PCI DSS compliance

2. Schema-First Approach

• ✅ Zod schemas for each platform's API config
• ✅ Runtime validation at OAuth time
• ✅ Type-safe TypeScript interfaces
• ✅ Self-documenting structure

3. Workflow-Based Architecture

• ✅ Route handler: 351 lines → 45 lines (87% reduction)
• ✅ Business logic in reusable workflow steps
• ✅ Clear separation of concerns
• ✅ Independently testable components

4. Eliminated Code Duplication

• ✅ Removed redundant /socials/publish-both endpoint
• ✅ Unified publishing logic across platforms
• ✅ Shared validation and error handling

---

Architecture Changes

Before

Route Handler (351 lines)
├── Platform detection
├── Token resolution
├── Content extraction
├── Validation
├── Smart retry logic
├── Publishing
└── Post update

After

Route Handler (45 lines)
└── Call Workflow

Workflow (Orchestration)
├── loadPostWithPlatformStep
├── validatePlatformAndCredentialsStep (with schema)
├── resolvePublishTargetStep (smart retry)
├── extractContentStep
├── validateContentCompatibilityStep
├── publishToTargetPlatformsStep
├── mergePublishResultsStep
└── updatePostWithResultsStep

---

Schema Structure

Platform API Config Schemas

Each platform has a validated schema stored in api_config:

Facebook:

{
  platform: "facebook",
  access_token: string,        // PAGE token
  token_type: "PAGE",
  page_id: string,
  page_access_token: string,
  user_access_token: string,
  user_id: string,
  scopes: string[],
  authenticated_at: string,
  expires_at: string,
  metadata: { pages: [...] }
}

Instagram:

{
  platform: "instagram",
  access_token: string,        // USER token
  token_type: "USER",
  user_id: string,
  ig_user_id: string,
  page_id: string,
  scopes: string[],
  authenticated_at: string,
  expires_at: string,
  metadata: { ig_accounts: [...] }
}

FBINSTA:

{
  platform: "fbinsta",
  access_token: string,        // PAGE token
  token_type: "PAGE",
  page_id: string,
  page_access_token: string,
  ig_user_id: string,
  user_access_token: string,
  scopes: string[],
  authenticated_at: string,
  expires_at: string,
  metadata: { pages: [...], ig_accounts: [...] }
}

Twitter/X:

{
  platform: "twitter",
  access_token: string,        // OAuth 2.0 token
  token_type: "USER",
  user_id: string,
  oauth1_credentials: {
    access_token: string,
    access_token_secret: string
  },
  scopes: string[],
  authenticated_at: string,
  expires_at: string
}

---

Benefits

1. Type Safety

• TypeScript interfaces for all platform configs
• Compile-time type checking
• IDE autocomplete support
• Reduced runtime errors

2. Runtime Validation

• Zod schemas validate at OAuth time
• Catch configuration errors early
• Prevent invalid data storage
• Clear error messages

3. Maintainability

• Route handlers: 87% smaller
• Clear separation of concerns
• Easy to add new platforms
• Simple to modify retry logic

4. Testability

• Each workflow step independently testable
• Mock dependencies easily
• Test retry logic in isolation
• Integration tests for complete flow

5. Observability

• Workflow execution tracking
• Step-by-step logging
• Easy to debug failures
• Clear rollback points

6. Self-Documenting

• Schema serves as documentation
• Example configs for each platform
• Clear field naming conventions
• Metadata for additional context

---

Implementation Phases

Phase 0: Security & Schema Foundation ⭐ START HERE

1. Implement Encryption Service

   • Create AES-256-GCM encryption service
   • Generate encryption keys for all environments
   • Add unit tests for encryption/decryption
   • Test key rotation support

2. Create Schemas with Encrypted Fields

   • Define Zod schemas for all platforms
   • Include encrypted field schemas
   • Add validation to OAuth callbacks
   • Test OAuth flow with encryption + validation

3. Migrate Existing Data

   • Backup database
   • Encrypt existing plaintext tokens
   • Verify all platforms work after migration
   • Deploy to production

Phase 1: Workflow Implementation

1. Create workflow steps directory
2. Implement all workflow steps
3. Create unified workflow
4. Add comprehensive tests

Phase 2: Route Refactoring

1. Update route handler to use workflow
2. Maintain backward compatibility
3. Test all publishing scenarios
4. Test smart retry logic

Phase 3: Documentation & Deployment

1. Update API documentation
2. Document schema structure
3. Deploy to staging
4. Deploy to production

Phase 4: Cleanup

1. Deprecate redundant endpoints
2. Remove after grace period

---

Success Metrics

Metric	Before	After	Improvement
Route Handler Size	351 lines	45 lines	87% reduction
Code Duplication	High	None	100% eliminated
Token Security	Plaintext	Encrypted	AES-256-GCM
Testability	Low	High	Independently testable
Type Safety	Partial	Full	Runtime + compile-time
Maintainability	Low	High	Clear separation
Observability	Limited	Full	Workflow tracking
Compliance	Basic	Full	GDPR/PCI DSS ready

---

Risk Assessment

Low Risk ✅

• Incremental implementation - No breaking changes
• Backward compatible - Existing API contracts maintained
• Schema validation - Catches errors at OAuth time
• Comprehensive tests - Unit + integration coverage

Mitigation Strategies

1. Schema validation prevents invalid configs
2. Workflow rollback handles failures gracefully
3. Monitoring tracks errors in production
4. Gradual rollout allows testing before full deployment

---

Next Steps

1. Review the four documentation files:

   • SOCIAL_POSTS_API_ANALYSIS.md - Current state analysis
   • /docs/implementation/security/encryption-service - Encryption implementation ⭐
   • /docs/reference/social-api/config-schema - Schema definitions
   • SOCIAL_POSTS_REFACTORING_PLAN.md - Implementation details

2. Start with Phase 0 - Security & Schema foundation

   • Implement encryption service (CRITICAL)
   • Generate encryption keys
   • Create Zod schemas with encrypted fields
   • Update OAuth callbacks
   • Encrypt existing tokens

3. Proceed to Phase 1 - Implement workflows

   • Create workflow steps with decryption
   • Build unified workflow
   • Add comprehensive tests

4. Complete refactoring - Update routes and deploy

---

Conclusion

This refactoring delivers:

• ✅ 87% code reduction in route handlers
• ✅ 100% elimination of code duplication
• ✅ AES-256-GCM encryption for all tokens ⭐
• ✅ Full type safety with schema validation
• ✅ Improved testability with workflow steps
• ✅ Better observability with workflow tracking
• ✅ GDPR/PCI DSS compliance ready
• ✅ Self-documenting code with schemas

The implementation is low-risk, incremental, and backward-compatible, making it a high-value improvement with minimal disruption.

Security is prioritized with encryption implemented before any token storage.

---

Documentation Index

1. SOCIAL_POSTS_API_ANALYSIS.md - Problem analysis and recommendations
2. /docs/implementation/security/encryption-service - Encryption implementation ⭐ CRITICAL
3. /docs/reference/social-api/config-schema - Schema definitions and examples
4. SOCIAL_POSTS_REFACTORING_PLAN.md - Step-by-step implementation guide
5. SOCIAL_POSTS_REFACTORING_SUMMARY.md - This document (executive overview)