AI-powered multi-platform content publishing made simple
๐ Live Demo ยท ๐ Documentation ยท ๐ Report Bug ยท โจ Request Feature
Alpha Release -- OmniPost is in active alpha. Core publishing workflows are functional and ready for early adopters. See the Alpha Launch Plan for current status and the Getting Started Guide for setup instructions.
- Why OmniPost?
- Features
- Quick Start
- Technology Stack
- Project Structure
- Available Scripts
- Configuration
- Deployment
- API Documentation
- Testing
- Documentation
- Architecture
- Contributing
- Troubleshooting
- License
New to OmniPost? The Getting Started Guide covers everything you need:
- Prerequisites and installation (5 steps)
- Platform API key setup (Facebook, Instagram, LinkedIn, Twitter)
- AI service configuration (OpenAI, Hugging Face)
- Common issues and troubleshooting
- Developer workflow and quality checks
The Problem: Content creators and marketing teams waste hours manually posting the same content across multiple platforms, dealing with different formatting requirements, character limits, and APIs for each social network.
The Solution: OmniPost is an AI-powered multi-platform content publishing platform built with Next.js 16 (App Router), React 19, and TypeScript. It streamlines content workflows from creation to publication across all major platforms with intelligent content adaptation, AI-powered text processing, and automated image generation.
- One Click, All Platforms: Publish to Facebook, Instagram, LinkedIn, Twitter, and custom platforms simultaneously
- AI-Powered Intelligence: Automatic content summarization, text parsing, and image generation
- Smart Content Adaptation: Automatically adjusts content for platform-specific requirements
- Human-in-the-Loop: Built-in review workflow ensures quality control before publishing
- Enterprise-Ready: JWT authentication, audit trails, rate limiting, and comprehensive security
Get OmniPost running on your machine in less than 5 minutes!
Before you begin, ensure you have the following installed:
- Node.js: v18.20.0 or higher (Download)
- pnpm: v9.0.0 or higher (Install pnpm)
- Git: Latest version (Download)
๐ก Tip: Use nvm to manage Node.js versions. This project includes a
.nvmrcfile for easy version switching.
# 1. Clone the repository
git clone https://github.com/phoenixvc/omnipost.git
cd omnipost
# 2. Install the correct Node.js version (if using nvm)
nvm use
# 3. Install dependencies using pnpm
pnpm install
# 4. Set up environment variables
cp .env.example .env.local
# 5. Configure your JWT secret (required)
# Edit .env.local and set JWT_SECRET=your-secure-random-string
# 6. Start the development server
pnpm dev๐ Success! Open http://localhost:3000 in your browser.
- Configure authentication: Set a secure
JWT_SECRETin your.env.localfile - Optional integrations: Add API keys for Airtable, Hugging Face, or notification services
- Explore the platform: Visit the live demo at https://nl-dev-omnipost-app-euw.azurewebsites.net
- Read the docs: Check out the Documentation Hub for detailed guides
๐ก Tip: This project uses pnpm as the package manager. All commands should be run with
pnpminstead ofnpm.
| Command | Description |
|---|---|
pnpm dev |
๐ Start development server at http://localhost:3000 |
pnpm build |
๐๏ธ Build the application for production |
pnpm start |
|
pnpm type-check |
๐ Run TypeScript type checking |
| Command | Description |
|---|---|
pnpm test |
๐งช Run all tests |
pnpm test:watch |
๐ Run tests in watch mode |
pnpm test:coverage |
๐ Generate test coverage report |
| Command | Description |
|---|---|
pnpm lint |
๐ Run ESLint to check code quality |
pnpm lint:fix |
๐ง Fix ESLint issues automatically |
pnpm format |
โจ Format code with Prettier |
pnpm format:check |
๐ Check code formatting |
pnpm check-all |
โ Run all quality checks (type-check + lint + format + test) |
# Before committing changes, run:
pnpm check-all
# For active development:
pnpm dev # In one terminal
pnpm test:watch # In another terminal- Multi-Platform Publishing: Seamlessly publish to Facebook, Instagram, LinkedIn, Twitter, and custom platforms
- Intelligent Content Adaptation: Automatically adjust content for different platforms and audiences
- Series Management: Organize and manage related content series efficiently
- Content Queue System: Review and approve content before publishing with human-in-the-loop workflow
- Comprehensive Tracking: Monitor content performance across all platforms
- Text Summarization: Generate intelligent summaries of raw text using state-of-the-art AI
- Smart Text Parsing: Parse and analyze text with support for multiple AI providers:
- DeepSeek
- OpenAI
- Azure OpenAI
- Image Generation: Create stunning images using Hugging Face API integration
- Content Optimization: AI-powered suggestions for improved engagement
- Airtable Integration: Persistent storage and tracking of published content
- JWT Authentication: Secure, industry-standard authentication and authorization
- Comprehensive Audit Trail: Track all system actions for compliance and debugging
- Dynamic Feature Flags: Control feature availability without redeployment
- Multi-Channel Notifications:
- ๐ง Email (via Nodemailer)
- ๐ฌ Slack integration
- ๐ฑ SMS (via Twilio)
- User Feedback System: Built-in mechanism for collecting and managing user feedback
- Performance Dashboard: Real-time engagement metrics and analytics
- Rate Limiting: Protect your API from abuse with intelligent rate limiting
- Input Sanitization: Enterprise-grade security with DOMPurify and Zod validation
omnipost/
โโโ ๐ app/ # Next.js App Router
โ โโโ api/ # New API route handlers (App Router)
โ โโโ ... # App Router pages and layouts
โโโ ๐ pages/ # Next.js Pages Router (legacy)
โ โโโ api/ # Legacy API routes (being migrated)
โ โโโ ... # Page components
โโโ ๐ components/ # React components
โ โโโ ui/ # Reusable UI components
โ โโโ features/ # Feature-specific components
โ โโโ layouts/ # Layout components
โ โโโ forms/ # Form components
โโโ ๐ lib/ # Core business logic
โ โโโ utils/ # Utility functions
โ โโโ services/ # External service integrations
โ โโโ ... # Core libraries
โโโ ๐ hooks/ # Custom React hooks
โโโ ๐ types/ # TypeScript type definitions
โโโ ๐ styles/ # Global styles and CSS modules
โโโ ๐ __tests__/ # Test files (mirrors source structure)
โโโ ๐ infra/ # Azure Bicep infrastructure templates
โโโ ๐ docs/ # Project documentation
โ โโโ api/ # API documentation
โ โโโ guides/ # Developer guides
โ โโโ ... # Additional docs
โโโ ๐ scripts/ # Build and deployment scripts
โโโ ๐ .github/ # GitHub workflows and configurations
โ โโโ workflows/ # CI/CD pipelines
โ โโโ copilot-instructions.md
โโโ ๐ Configuration files # TypeScript, ESLint, Jest, etc.
๐ Note: The project is currently migrating from Pages Router to App Router. New features should use the App Router (
app/api/). See API Migration Guide for details.
For a detailed breakdown, see PROJECT_STRUCTURE.md.
OmniPost uses environment variables for configuration. Create a .env.local file in the root directory:
cp .env.example .env.local# Authentication - REQUIRED for the application to run
JWT_SECRET=your-secure-jwt-secret-key-minimum-32-characters๐ Security Tip: Generate a secure JWT secret using:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
Airtable Integration - Content storage and tracking
AIRTABLE_API_KEY=your-airtable-api-key
AIRTABLE_BASE_ID=your-airtable-base-id
AIRTABLE_TABLE_NAME=your-airtable-table-nameGet your Airtable API key from Airtable Account.
Hugging Face - AI image generation
HUGGING_FACE_API_KEY=your-hugging-face-api-keyCreate an API key at Hugging Face.
Email Notifications - Gmail integration
EMAIL_USER=your-email@gmail.com
GMAIL_CLIENT_ID=your-gmail-client-id
GMAIL_CLIENT_SECRET=your-gmail-client-secret
GMAIL_REFRESH_TOKEN=your-gmail-refresh-tokenFollow Gmail API setup guide for credentials.
Slack Notifications - Team notifications
SLACK_TOKEN=xoxb-your-slack-bot-tokenCreate a Slack app and bot at Slack API.
Twilio SMS - SMS notifications
TWILIO_ACCOUNT_SID=your-twilio-account-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
TWILIO_PHONE_NUMBER=+1234567890Get credentials from Twilio Console.
Social Platform APIs - Direct publishing integrations
# Facebook
FACEBOOK_API_URL=https://graph.facebook.com
FACEBOOK_API_KEY=your-facebook-api-key
# Instagram
INSTAGRAM_API_URL=https://graph.instagram.com
INSTAGRAM_API_KEY=your-instagram-api-key
# LinkedIn
LINKEDIN_API_URL=https://api.linkedin.com
LINKEDIN_API_KEY=your-linkedin-api-key
# Twitter/X
TWITTER_API_URL=https://api.twitter.com
TWITTER_API_KEY=your-twitter-api-keySee .env.example for the complete configuration template.
OmniPost is optimized for Azure Web Apps with Next.js standalone output mode for production deployments.
- โ 90% smaller deployments (~86MB vs ~800MB)
- โ Faster cold starts with run-from-package mode
- โ Automated quality gates (type-check, lint, tests)
- โ Health check verification post-deployment
- โ Application Insights monitoring with automated alerts
- โ Build caching for faster subsequent deployments
Automatic Deployment:
- Push to
mainbranch โ Automatically deploys to dev environment - Manual deployment: GitHub Actions โ Run workflow โ Select environment (dev/test/prod)
Deployment Time: 10-15 minutes total
- Build Phase: 5-7 minutes
- Infrastructure Phase: 2-3 minutes
- Deploy Phase: 3-5 minutes
- Azure subscription with appropriate permissions
- Azure CLI installed (for manual deployment)
- GitHub repository secrets configured:
AZURE_CREDENTIALS- Service principal for Azure deploymentAZURE_CLIENT_ID,AZURE_TENANT_ID,AZURE_SUBSCRIPTION_ID- See docs/AZURE_SECRETS.md for detailed configuration
GitHub Actions Configuration (.github/workflows/azure-webapps-node.yml):
env:
NODE_VERSION: '18.20.0' # Must match .nvmrc
ORG_CODE: 'nl' # Organization code
PROJECT_NAME: 'omnipost'
REGION_CODE: 'euw' # Region: euw, eus, etc.
LOCATION: 'westeurope' # Azure regionInfrastructure Configuration (infra/parameters.json):
{
"org": { "value": "nl" },
"env": { "value": "dev" },
"project": { "value": "omnipost" },
"region": { "value": "euw" },
"sku": { "value": "B1" },
"enableMonitoring": { "value": true },
"enableDeploymentSlot": { "value": false }
}# Basic deployment (dev environment)
./scripts/deploy-infrastructure.ps1
# Preview changes without deploying (what-if mode)
./scripts/deploy-infrastructure.ps1 -Preview
# Deploy to production
./scripts/deploy-infrastructure.ps1 -Environment prod -Location eastus -LocationCode eus
# Deploy with specific SKU
./scripts/deploy-infrastructure.ps1 -Environment test -Sku S1
# Skip login if already authenticated
./scripts/deploy-infrastructure.ps1 -SkipLoginThe script will:
- Authenticate with Azure (via
az login) - Create the resource group if it doesn't exist
- Deploy the Bicep template with the specified configuration
- Display deployment outputs (Web App name and URL)
-
Build Phase (~5-7 min)
- Install dependencies with pnpm
- Run TypeScript type-check
- Run ESLint for code quality
- Build Next.js standalone output
- Run test suite
- Create optimized deployment package (~86MB)
-
Infrastructure Phase (~2-3 min)
- Create/update Azure resources via Bicep IaC
- Configure App Service settings
- Set up Application Insights monitoring (if enabled)
- Configure alerts and dashboards
-
Deploy Phase (~3-5 min)
- Upload package to Azure Storage
- Deploy to App Service
- Start application
- Verify health endpoint with retries
- Warm-up requests
For detailed deployment instructions, see:
OmniPost provides a comprehensive REST API for content management and publishing.
| Endpoint | Method | Description |
|---|---|---|
/api/auth |
POST | User login and token generation |
/api/auth |
GET | Get current authenticated user |
/api/auth |
DELETE | User logout and token invalidation |
| Endpoint | Method | Description |
|---|---|---|
/api/content |
POST | Store content in Airtable |
/api/content |
GET | Retrieve and track content |
/api/queue/approve |
POST | Approve content in review queue |
| Endpoint | Method | Description |
|---|---|---|
/api/parse |
POST | Parse and analyze text with AI |
/api/summarize |
POST | Generate intelligent text summaries |
/api/images |
POST | Generate images using AI |
| Endpoint | Method | Description |
|---|---|---|
/api/platforms |
GET | List all available publishing platforms |
/api/platforms/[id]/capabilities |
GET | Get platform-specific capabilities |
| Endpoint | Method | Description |
|---|---|---|
/api/audit |
GET | Retrieve system audit logs |
/api/feature-flags |
GET | Get and manage feature flags |
/api/feedback |
POST | Submit user feedback |
/api/notifications |
POST | Send multi-channel notifications |
For detailed API documentation, including request/response schemas, authentication requirements, and examples:
- Route Files: Inline documentation in
/app/api/directory - API Reference: docs/API_REFERENCE.md
- Best Practices: docs/api/next-api-best-practices.md
- Migration Status: docs/api/api-migration-todo.md
- JWT Authentication: Secure token-based authentication
- Rate Limiting: Protect against API abuse
- Input Sanitization: DOMPurify + Zod validation
- CORS Configuration: Secure cross-origin requests
- Security Headers: Industry-standard security headers
OmniPost uses Jest and React Testing Library for comprehensive testing.
# Run all tests
pnpm test
# Run tests in watch mode (for active development)
pnpm test:watch
# Generate coverage report
pnpm test:coverageTests are organized to mirror the source code structure in the __tests__/ directory:
__tests__/
โโโ api/ # API route tests
โโโ components/ # Component tests
โโโ lib/ # Utility and service tests
โโโ integration/ # Integration tests
- Unit Tests: Test individual functions and components in isolation
- Integration Tests: Test API routes and service interactions
- Component Tests: Test React components with React Testing Library
- Coverage Target: Aim for >80% code coverage for critical paths
Current test status and known issues: docs/TEST_STATUS.md
// Example component test
import { render, screen } from '@testing-library/react';
import { MyComponent } from '@/components/MyComponent';
describe('MyComponent', () => {
it('renders correctly', () => {
render(<MyComponent title="Test" />);
expect(screen.getByText('Test')).toBeInTheDocument();
});
});For more testing guidelines, see CONTRIBUTING.md.
| Category | Technologies |
|---|---|
| Frontend | React 19, Next.js 16 (App Router), TypeScript 5.3 |
| Styling | CSS Modules, Global CSS |
| ORM / Database | Prisma 7, PostgreSQL |
| API | Next.js Route Handlers, RESTful API design |
| Authentication | JWT tokens, async middleware |
| Validation | Zod 3 schemas, DOMPurify sanitization |
| Testing | Jest 29, React Testing Library, jest-axe |
| Deployment | Azure Web Apps, Bicep IaC |
| CI/CD | GitHub Actions |
| AI Services | Hugging Face (image generation), OpenAI, DeepSeek, Azure AI |
| Integrations | Slack, Twilio, Nodemailer |
| Package Manager | pnpm 9 |
- App Router First: All new development uses the Next.js App Router (
app/api/) - Security-First: Rate limiting, input sanitization, RBAC, audit logging, OWASP Top 10 compliance
- Type Safety: Full TypeScript strict mode with no
anytypes - Modern Stack: React 19, Next.js 16, Prisma 7, Zod 3
- Scalable Infrastructure: Azure-native deployment with Bicep IaC templates
OmniPost follows a layered architecture built on the Next.js App Router:
Frontend (React 19, CSS Modules)
|
Next.js App Router (API Routes, Middleware, SSR)
|
Business Logic (Auth, Validation, Feature Flags)
|
Data Layer (Prisma 7 + PostgreSQL)
|
External Services (OpenAI, Hugging Face, Slack, Twilio)
Key architectural decisions:
- Prisma 7 with PostgreSQL for structured data persistence and type-safe queries
- JWT-based authentication with async
isAuthenticated()checks in every protected route - Zod schemas for runtime input validation on all API endpoints
- DOMPurify for HTML sanitization to prevent XSS
- Rate limiting on all public-facing endpoints via
withRateLimitwrapper - Feature flags for controlling functionality without redeployment
For the full architecture documentation, see docs/ARCHITECTURE.md.
| Document | Description |
|---|---|
| Documentation Hub | Complete documentation index and overview |
| Architecture Guide | Technical architecture and design decisions |
| Project Structure | Detailed directory organization |
| Contributing Guidelines | How to contribute to the project |
| Security Policy | Security practices and vulnerability reporting |
| Document | Description |
|---|---|
| GitHub Copilot Instructions | AI coding assistant guidelines |
| API Best Practices | API development standards |
| API Migration Guide | Pages to App Router migration status |
| Next.js Best Practices | Framework-specific patterns |
| Document | Description |
|---|---|
| Code of Conduct | Community guidelines and expectations |
| Changelog | Version history and release notes |
| License | MIT License details |
| Environment Variables | Configuration template and examples |
| Deployment Guide | Detailed deployment instructions |
| Azure Secrets Setup | Azure configuration guide |
- Setting up development environment: Quick Start
- Understanding the codebase: Project Structure
- Adding a new feature: Contributing Guidelines
- Deploying to production: Deployment
- Reporting a security issue: Security Policy
- API development: API Best Practices
โ Missing environment variables
Error: Application fails to start or returns 500 errors
Solution:
# Ensure .env.local exists
cp .env.example .env.local
# Set required JWT_SECRET
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Copy the output to JWT_SECRET in .env.localVerify JWT_SECRET is configured in .env.local
๐ Authentication errors
Error: "Unauthorized" or "Invalid token" errors
Solutions:
- Verify
JWT_SECRETmatches between client and server - Check if token has expired (tokens have limited lifetime)
- Clear browser cookies and local storage
- Restart the development server
๐๏ธ Airtable connection issues
Error: Cannot connect to Airtable or save content
Solutions:
- Verify
AIRTABLE_API_KEY,AIRTABLE_BASE_ID, andAIRTABLE_TABLE_NAMEare correct - Check Airtable API permissions for your API key
- Ensure Airtable base is shared with the API key owner
- Test API key at Airtable API
๐๏ธ Build errors
Error: Build fails with TypeScript or dependency errors
Solutions:
# Clear all caches and rebuild
rm -rf node_modules .next pnpm-lock.yaml
pnpm install
pnpm build
# If TypeScript errors persist
pnpm type-check๐งช Test failures
Error: Tests fail during pnpm test
Solutions:
# Clear Jest cache
pnpm test --clearCache
# Reinstall dependencies
rm -rf node_modules
pnpm install
# Run tests with verbose output
pnpm test --verboseCheck docs/TEST_STATUS.md for known test issues.
๐ Port already in use
Error: "Port 3000 is already in use"
Solutions:
# Find and kill process on port 3000
lsof -ti:3000 | xargs kill -9
# Or use a different port
PORT=3001 pnpm dev๐ฆ Package manager issues
Error: "Command not found: pnpm" or version conflicts
Solutions:
# Install pnpm globally
npm install -g pnpm@9.0.0
# Or use npx
npx pnpm install
# Use correct Node.js version
nvm use # Reads from .nvmrcโ๏ธ Azure deployment failures
Error: "Cannot find module 'styled-jsx/package.json'" or container startup failures
Solutions:
This has been fixed in the repository. Ensure you have the latest code:
# Pull latest changes
git pull origin main
# Verify .npmrc exists
cat .npmrc
# Should contain: node-linker=hoisted
# Rebuild and redeploy
pnpm install
pnpm buildWhat was the issue?
- pnpm's default isolated module structure wasn't compatible with Azure
- The
.npmrcfile now configures hoisted node_modules for Azure compatibility - See AZURE_DEPLOYMENT_FIX.md for detailed explanation
Manual Azure fix (if needed):
# Set startup command via Azure CLI
az webapp config set --name <app-name> \
--resource-group <resource-group> \
--startup-file "node server.js"
# Restart the app
az webapp restart --name <app-name> \
--resource-group <resource-group>For more details, see:
If you're still experiencing problems:
- Check existing issues: GitHub Issues
- Review documentation: Documentation Hub
- Create a new issue: Provide detailed error messages and steps to reproduce
- Check logs: Look at browser console and terminal output for error details
- GitHub Issues: Report bugs or request features
- Discussions: Ask questions and share ideas
- Documentation: Browse the docs
We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.
- Fork the repository
- Create a feature branch
git checkout -b feature/amazing-feature
- Make your changes
- Follow the coding standards
- Write tests for new features
- Update documentation as needed
- Run quality checks
pnpm check-all # Runs type-check, lint, format check, and tests - Commit your changes
Use conventional commits format
git commit -m 'feat: add amazing feature' - Push to your branch
git push origin feature/amazing-feature
- Open a Pull Request
For detailed contribution guidelines, please read CONTRIBUTING.md.
Key points:
- Follow TypeScript strict mode and coding standards
- Write tests for all new features
- Ensure all quality checks pass before submitting PR
- Use meaningful commit messages
- Update documentation for significant changes
- Be respectful and follow our Code of Conduct
Found a bug or have a feature request?
- Bug Reports: Create an issue with detailed reproduction steps
- Feature Requests: Create an issue describing the feature and use case
- Security Issues: See our Security Policy for responsible disclosure
- Documentation: Check the docs folder for guides
- Issues: Search existing issues for similar questions
- Discussions: Start a GitHub Discussion for general questions
- ๐ Fix bugs and issues
- โจ Add new features
- ๐ Improve documentation
- ๐งช Write tests
- ๐จ Enhance UI/UX
- ๐ Review pull requests
- ๐ก Share ideas and feedback
This project is licensed under the MIT License - see the LICENSE file for details.
- โ Commercial use allowed
- โ Modification allowed
- โ Distribution allowed
- โ Private use allowed
โ ๏ธ License and copyright notice required- โ Liability and warranty not provided
JustAGhosT - Creator and Lead Developer
- GitHub: @JustAGhosT
- Repository: content_creation
Special thanks to:
- Next.js Team - For the excellent React framework
- Vercel - For Next.js and deployment inspiration
- Hugging Face - For AI capabilities and models
- Airtable - For flexible data storage solutions
- Azure - For enterprise cloud hosting
- Open Source Community - For amazing tools and libraries
- All Contributors - For improvements, bug fixes, and feedback
This project builds upon these amazing open-source technologies:
- React - UI library
- Next.js - React framework
- TypeScript - Type safety
- Jest - Testing framework
- Azure - Cloud platform
- ๐ Alpha Release: Core workflows functional, ready for early adopters
- โ Deployed: Running on Azure Web Apps
- โ CI/CD Pipeline: Automated testing and deployment via GitHub Actions
- โ Auth & Security: JWT middleware, rate limiting, input sanitization all operational
โ ๏ธ Test Coverage: Actively improving toward 80%+ target
๐ฎ Planned Features
- Additional AI provider integrations (Claude, Gemini)
- Enhanced analytics and reporting dashboard
- Bulk content scheduling and management
- Content templates and reusable snippets
- Advanced image editing capabilities
- Multi-user collaboration features
- Custom platform integrations via plugins
- Mobile app (iOS/Android)
๐ง Technical Improvements
- Complete Pages Router to App Router migration
- Increase test coverage to 90%+
- Redis integration for distributed rate limiting
- WCAG 2.1 AA compliance
- Performance optimization (Core Web Vitals)
- Design system formalization
- Production monitoring setup (Sentry/DataDog)
See CHANGELOG.md for version history and GitHub Projects for current progress.
- ๐ Live Demo: https://nl-dev-omnipost-app-euw.azurewebsites.net
- ๐ฆ Repository: github.com/phoenixvc/omnipost
- ๐ Issues: GitHub Issues
- ๐ฌ Discussions: GitHub Discussions
- ๐ Documentation: Documentation Hub
- ๐ก Feature Requests: Request a Feature
- ๐ Bug Reports: Report a Bug
- ๐ Security: Security Policy
- ๐ค Contributing: Contributing Guidelines
โญ If you find OmniPost useful, please consider giving it a star on GitHub! โญ
Made with โค๏ธ by JustAGhosT