SocialAi is a lightweight, AI‑powered social discovery engine that mirrors public Farcaster activity, blends optional Reddit timelines, and exposes SEO‑optimized public profiles that users can claim by verifying their Farcaster identity.
It is built on a parallel, auto‑healing, one‑file node architecture powered by Healdec and SmartBrain.
Built with Node.js 24+ | Production-Ready | Modern GitHub-Style UI
Screenshot coming soon. Once available, add it as
docs/screenshots/public-app.pngand replace this note with an embedded image. Modern GitHub-inspired dark theme for public profiles and timelines
Screenshot coming soon. Once available, add it as
docs/screenshots/admin-dashboard.pngand replace this note with an embedded image. Real-time system metrics and worker health monitoring
Screenshot coming soon. Once available, add it as
docs/screenshots/desktop-admin.pngand replace this note with an embedded image. Native Windows admin app built with Tauri
- SEO‑optimized profiles, posts, timelines
- Google‑indexable pages
- Zero‑JS by default (Astro + Vite)
- Fast SSR for timelines and profiles
- GitHub-inspired dark theme UI
- Farcaster Sign‑In
- Wallet verification (SIWE)
- ENS mapping
- Claim → unlock editing + AI tools
- Farcaster Hub ingestion
- Optional Reddit sync
- Future: Lens, Bluesky, Zora
- Admin‑controlled feed toggles
- Embeddings + vector search
- Timeline summaries
- Profile optimization
- Topic clustering
- Recommendations
- Follow / unfollow
- Likes
- Saved posts
- Mutuals
- Feature flags
- Sync toggles
- Logs
- Worker health
- Abuse controls
- NEW: Desktop Windows app (Tauri)
For a detailed architecture diagram and component descriptions, see docs/ARCHITECTURE.md.
- SEO pages
- Profiles
- Timelines
- Claim flow
- Landing pages
- Feature flags
- Sync controls
- Worker monitoring
- System health
- Healdec engine
- Parallel chain workers
- AI worker
- Search worker
- Sync worker
- RPC workers
- Users
- Profiles
- Posts
- External posts
- Follows
- Likes
- Claims
- Embeddings
- Feature flags
- Settings
- Node.js 24+ (specified in
.nvmrc) - PostgreSQL 12+
- npm 10+
git clone https://github.com/SMSDAO/SocialAi.git
cd SocialAi
# Automated setup (zero-error, one-click)
npm run setupThe setup script will:
- ✅ Check Node.js version (24+)
- ✅ Create
.envfrom.env.example - ✅ Install all dependencies
- ✅ Validate configuration
# 1. Clone the repository
git clone https://github.com/SMSDAO/SocialAi.git
cd SocialAi
# 2. Use Node.js 24+
nvm use # Reads from .nvmrc
# 3. Install dependencies
npm install
# 4. Setup database
createdb socialai
psql -U postgres -d socialai -f db/schema.sql
# 5. Configure environment
cp .env.example .env
# Edit .env with your settings (see .env.example for all options)
# 6. Start the system
npm run dev # Backend + Workers
npm run dev:public # Public App (port 4321)
npm run dev:admin # Admin Console (port 4200)
npm run dev:desktop # Desktop Admin App (Windows)Note: These manual steps mirror what the automated setup script (
npm run setup) does internally. You can either runnpm run setupor follow the commands above manually—both paths achieve the same result.
- 🔌 Backend API: http://localhost:3000
- 🌐 Public App: http://localhost:4321
- ⚙️ Admin Console: http://localhost:4200
- 🖥️ Desktop Admin: Native Windows app (via Tauri)
Build the native Windows admin app:
# Prerequisites: Rust toolchain + Node.js 24+
npm run build:desktop:windowsThe installer will be created in desktop-admin/src-tauri/target/release/bundle/:
admin.msi- MSI installeradmin-setup.exe- NSIS installer
For detailed desktop app documentation, see desktop-admin/README.md.
For detailed setup instructions, see docs/INSTALLATION.md.
The public frontend is optimized for Vercel deployment with Node.js 24 runtime.
- Install Vercel CLI:
npm install -g vercel- Deploy:
vercelThe vercel.json configuration is already set up with:
- ✅ Node.js 24 runtime
- ✅ Optimized build settings
- ✅ Correct output directory
- ✅ Environment variable placeholders
Configure these in your Vercel project settings (frontend only):
PUBLIC_API_URL- Backend API URL (e.g., https://api.yourdomain.com)
Note: Backend secrets (DATABASE_URL, JWT_SECRET, SESSION_SECRET) should only be configured in your backend deployment environment (Railway, Render, etc.), not in Vercel frontend settings.
The backend can be deployed to any Node.js 24+ hosting provider:
- Recommended: Railway, Render, Fly.io
- Requirements: Node.js 24+, PostgreSQL 12+
- Build command:
npm install - Start command:
npm run dev
Automated workflows are configured in .github/workflows/:
- ✅ CI: Runs on every push/PR (Node 24 checks, builds)
⚠️ Deploy: Workflow exists and currently runs build checks only; Vercel deployment is not yet implemented (TODO and will require Vercel token configuration once enabled).
- Set
NODE_ENV=productionin environment - Configure production database
- Set strong JWT and session secrets
- Configure CORS origins
- Enable rate limiting
- Set up monitoring and logging
- Review security settings
For detailed deployment instructions, see docs/DEPLOYMENT.md.
- 📖 Documentation Index - Complete documentation table of contents
- ⚙️ Installation Guide - Complete setup and deployment guide
- 🏗️ Architecture - System architecture and component diagrams
- 🎨 UI/UX Specifications - User interface and user experience guidelines
- 🔌 API Reference - Full API documentation with examples
- 💻 Development Guide - Development workflow and best practices
- 🤝 Contributing Guidelines - How to contribute to the project
- ✅ Testing Guide - Testing strategies and commands
- 🔧 Troubleshooting - Common issues and solutions
- 🚀 Deployment Guide - Production deployment instructions
- 🔒 Security Summary - Security vulnerabilities and remediation
For a comprehensive overview and quick navigation, start with the Documentation Index.