Social Media Analytics Dashboard

A comprehensive social media analytics platform that aggregates data from Twitter/X, Facebook, and LinkedIn into a unified dashboard. Built with modern web technologies and designed for scalability.

🚀 Features

• Multi-Platform Integration: Connect and sync data from Twitter/X, Facebook, and LinkedIn
• Real-Time Analytics: View follower growth, engagement metrics, and post performance
• Automated Data Collection: Background workers fetch data every 30 minutes
• Secure OAuth Integration: Industry-standard OAuth 2.0 implementation with PKCE
• Beautiful Dashboard: Modern, responsive UI with dark/light theme support
• ngrok Integration: Seamless local development with public URLs

🛠️ Tech Stack

Backend

• NestJS - Progressive Node.js framework
• PostgreSQL - Primary database
• TypeORM - Object-relational mapping
• JWT - Authentication
• OAuth 2.0 - Social media authentication
• Bull - Job queue for background tasks

Frontend

• React 19 - UI library
• TypeScript - Type safety
• Material-UI - Component library
• Zustand - State management
• Recharts & Nivo - Data visualization
• Vite - Build tool

📋 Prerequisites

• Node.js 18+ and npm
• PostgreSQL 12+
• Social media developer accounts (Twitter/X, Facebook, LinkedIn)
• ngrok account (optional, for OAuth development)

🚀 Quick Start

1. Clone the repository

git clone https://github.com/yourusername/social-media-analytics-dashboard.git
cd social-media-analytics-dashboard

2. Backend Setup

cd backend
npm install

# Create .env from example
cp .env.example .env

# Update .env with your credentials:
# - Database connection
# - JWT secret
# - Social media API keys

# Run database migrations
npm run typeorm migration:run

# Start development server
npm run start:dev

3. Frontend Setup

cd frontend
npm install

# Start development server
npm run dev

4. Access the application

• Frontend: https://localhost:5173
• Backend API: http://localhost:3000
• API Documentation: http://localhost:3000/api-docs

🔐 Environment Variables

Backend (.env)

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your_password
DB_DATABASE=social_dashboard_db

# JWT
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=3600s

# Social Media API Keys
TWITTER_CLIENT_ID=your_twitter_client_id
TWITTER_CLIENT_SECRET=your_twitter_client_secret
FACEBOOK_APP_ID=your_facebook_app_id
FACEBOOK_APP_SECRET=your_facebook_app_secret
LINKEDIN_CLIENT_ID=your_linkedin_client_id
LINKEDIN_CLIENT_SECRET=your_linkedin_client_secret

# URLs
APP_BASE_URL=http://localhost:3000
FRONTEND_BASE_URL=http://localhost:5173

# Encryption
ENCRYPTION_KEY=your_32_byte_hex_key

Frontend (.env)

# Optional: Override backend URL for production
VITE_API_BASE_URL=https://your-backend-url.com

🌐 ngrok Development

The project includes automatic ngrok integration for OAuth callback testing:

# Backend with ngrok
cd backend && npm run start:ngrok

# Frontend will auto-discover the ngrok URL
cd frontend && npm run dev

📱 Social Media Setup

Twitter/X

1. Create app at https://developer.twitter.com
2. Enable OAuth 2.0
3. Add callback URL: http://localhost:3000/connect/twitter/callback
4. Request scopes: tweet.read, users.read, offline.access

Facebook

1. Create app at https://developers.facebook.com
2. Add Facebook Login product
3. Add callback URL: http://localhost:3000/connect/facebook/callback
4. Request permissions: pages_read_engagement, pages_show_list

LinkedIn

1. Create app at https://www.linkedin.com/developers
2. Add callback URL: http://localhost:3000/connect/linkedin/callback
3. Request scopes: r_liteprofile, r_organization_social

🏗️ Architecture

social-media-analytics-dashboard/
├── backend/
│   ├── src/
│   │   ├── auth/          # JWT authentication
│   │   ├── users/         # User management
│   │   ├── connect/       # OAuth integration
│   │   ├── platforms/     # Platform-specific services
│   │   ├── feed/          # Aggregated social feed
│   │   ├── analytics/     # Analytics processing
│   │   └── worker/        # Background jobs
│   └── test/
├── frontend/
│   ├── src/
│   │   ├── components/    # Shared components
│   │   ├── features/      # Feature modules
│   │   ├── stores/        # Zustand stores
│   │   └── lib/           # Utilities
│   └── public/
└── docs/

🧪 Testing

# Backend tests
cd backend
npm run test
npm run test:e2e

# Frontend tests (to be implemented)
cd frontend
npm run test

📦 Deployment

Production Build

# Backend
cd backend
npm run build
npm run start:prod

# Frontend
cd frontend
npm run build
npm run preview

Docker Support (Coming Soon)

• Dockerfiles for both frontend and backend
• Docker Compose for full stack deployment
• Kubernetes manifests for cloud deployment

🤝 Contributing

This project was primarily developed by Gauntlit AI with contributions from Andrew Peltekci.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

Copyright 2025 Gauntlit AI

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

🙏 Acknowledgments

• Built with ❤️ by Gauntlit AI
• Project initiated by Andrew Peltekci
• Powered by Claude AI assistance

📞 Support

For issues and feature requests, please use the GitHub Issues page.

---

Note: This project is under active development. Features and documentation are subject to change.