Overseek Socials
AI-powered social media management for brands and agencies
Plan, publish, analyze, and collaborate across channels from one workspace.
What it does •
Core capabilities •
Quick start •
Tech stack •
Development
## What it does
Overseek Socials is a full social media operations platform built for teams that need speed, consistency, and visibility. It combines multi-platform scheduling, AI-assisted content workflows, and cross-channel analytics in one product.
## Core capabilities
- **Multi-platform publishing**: Compose once and publish to Instagram, TikTok, YouTube, Facebook, Pinterest, Bluesky, and Google Business Profile.
- **MCP integration**: Let other software upload media, publish immediately, and read workspace analytics through an authenticated, workspace-scoped [MCP server](docs/mcp-publishing.md) (no draft or scheduling tools).
- **AI content engine**: Generate captions, rewrite copy, create alt text, suggest tags, and keep output aligned with your brand voice.
- **Content calendar**: Use drag-and-drop week/month planning with visual platform cues and quick post creation.
- **Publishing queues**: Define each profile's recurring posting days and times, then bulk-upload files, spreadsheets, or library selections and have them distributed into those slots automatically. [Details](docs/publishing-queues.md).
- **Analytics and ROI tracking**: Monitor post performance and connect Shopify or WooCommerce for revenue attribution.
- **Reputation and engagement**: Track interactions, review sentiment, and manage responses from a unified workflow.
- **Team operations**: Support role-based access, workspace isolation, and collaboration for agencies managing multiple brands.
### Advisory inbox presence (backend API)
Presence is **advisory only, never a lock**: it neither reserves an inbox item nor prevents concurrent replies or notes. It stores no drafts or message content and requires no schema migration or frontend integration.
- `GET /api/inbox/presence?id=localRowId&type=comment|mention|dm|review&socialAccountId=...`
- `PUT /api/inbox/presence` with JSON `{id,type,socialAccountId,tabId,state}`; `tabId` must be a UUID and `state` is `viewing`, `replying`, or `noting`.
- GET and PUT return `{data:{participants:[{userId,name,state,updatedAt}],ttlSeconds:45}}`. `updatedAt` is an ISO timestamp. All tabs of the current user are excluded. Other users are grouped by highest activity (`replying > noting > viewing`), using the newest lease at that priority for name/timestamp, sorted by user ID.
- `DELETE /api/inbox/presence` with JSON `{id,type,socialAccountId,tabId}` releases only the authenticated user's specified tab and returns `{success:true}` (also when already absent).
Every request checks current organization membership and resolves an owned local row/account. DMs share presence across local messages in the same account/conversation. VIEWER can read, heartbeat `viewing`, and release; `replying`/`noting` require collaboration write permission (including same-organization CUSTOM `posts.edit`). Actor identity/name come from server-side membership, never request data.
Redis uses app `REDIS_URL` (default `redis://localhost:6379`) with a dedicated connection, a 1-second total Redis deadline, and no retries/offline queue. Atomic hash/sorted-set leases expire independently after 45 seconds; reads do not renew them. Maximum 200 active user/tab leases per canonical item; existing leases can refresh at capacity. New leases at capacity return 429. IDs are bounded to 256 characters, JSON bodies to 4096 bytes, and unknown fields/duplicate query parameters are rejected. Errors are explicit: 400 invalid input, 401 unauthenticated, 403 membership/write permission, 404 unowned/missing item, 413 oversized body, 429 capacity, 503 Redis failure/timeout, 500 unexpected backend failure. Responses are private/no-store; 503 never masquerades as an empty participant list.
Clients must heartbeat before expiry and treat missing/stale presence as advisory. Abruptly closed tabs and permission/name changes can remain visible until expiry or the next heartbeat. Concurrent requests are ordered by Redis arrival, so a late heartbeat can recreate a released lease. A timed-out write may have reached Redis; its lease still expires normally. No polling/SSE client or reply exclusion is provided by this backend.
Presence tests live in `app/src/app/api/inbox/presence/__tests__/`. Mocked transport/API and pure aggregation tests run normally. The Lua integration suite is opt-in via `INBOX_PRESENCE_TEST_REDIS_URL` pointing to a disposable **test-only** Redis instance; it uses random test keys and deletes only those keys, with no scans or flushes. Never point this test variable at production.
## Screenshots
Analytics Dashboard
Post Composer
Content Calendar
Media Library
## Quick start
### Prerequisites
- Docker + Docker Compose
- Node.js 20+ (local development)
### 1) Clone and configure
```bash
git clone https://github.com/MerlinStacks/socaliseit.git
cd socaliseit
cp stack.env.example stack.env
```
Update `stack.env` with database values, OAuth provider credentials, and your `OPENROUTER_API_KEY`.
### 2) Start services
```bash
docker network create proxy-net # Once per Docker host, if it does not already exist
docker compose --env-file stack.env up -d --build
```
Open `http://localhost:6754`.
The webapp and worker build locally from this checkout. GitHub Actions validates
the code and Docker builds, but does not publish deployment images. Deployments
do not need GHCR or a completed Actions run. The first build takes longer and
uses CPU, RAM and disk on the Docker host; later builds reuse cached layers.
### 3) Finish setup
1. Register your workspace owner account.
2. Connect at least one social platform.
3. Create and schedule your first post.
### Portainer: migrate an existing installation to local builds
Use a **Git repository stack on Docker Standalone**, with a Portainer/Compose
version that supports `pull_policy: build`. Swarm stack deployments do not build
images. The repository is still fetched from GitHub; Actions and GHCR are no
longer part of deployment.
1. Update the **existing stack**, keeping its current Compose path
(`docker-compose.yml` or `docker-compose.portainer.yml`), stack name,
environment variables and volume configuration. These files have different
defaults, so do not switch between them during migration.
2. Disable **Re-pull image** (called **Pull latest image** in older Portainer
versions), including in GitOps update settings.
3. Pull the latest repository changes and redeploy. Portainer builds the Dockerfile's
`webapp` and `worker` targets locally, then replaces their containers. Check
both services are healthy after deployment.
Both Compose files retain the existing named volumes for PostgreSQL, Redis,
MinIO, uploads and generated secrets, along with the existing service/network
names and startup behavior. Keep your existing `AUTH_SECRET`, `ENCRYPTION_KEY`
and database credentials. Do not remove the stack's volumes during migration.
Keep the existing `docker-init.sh` bind-mount setup available on the Docker host.
Subsequent Git-backed redeployments rebuild from the checked-out source using
the build cache, even when only application code changed. GitOps polling can
deploy a commit before CI finishes; use manual updates after CI passes if you
want to retain that release gate.
For an existing CLI installation, update its checkout with `git pull` and run
`docker compose up -d --build` using the same `-f`, `--env-file` and project-name
options as before. A stack created through Portainer's web editor or YAML upload
needs access to the full repository build context; replacing its YAML alone is
not enough. Installations still using old GHCR-only Compose definitions must
adopt the updated definitions to receive future releases.
## Tech stack
| Layer | Technology |
|-------|------------|
| Framework | Next.js App Router |
| Frontend | React 19 + Tailwind CSS 4 |
| Backend | Next.js API routes + background workers |
| Database | PostgreSQL + Prisma ORM |
| Queue | Redis + BullMQ |
| Auth | NextAuth (OAuth + credentials + TOTP) |
| Billing | Stripe |
| Deployment | Docker Compose |
## Project structure
```text
socaliseit/
├── app/
│ ├── src/ # Next.js app, API routes, components, services
│ └── prisma/ # Prisma schema and migrations
├── docs/ # Product and technical docs
├── docker-compose.yml
└── docker-compose.dev.yml
```
## Development
```bash
cd app
npm install
npm run dev
```
Common commands:
```bash
npm run build
npm run test
npm run test:e2e
npm run test:coverage
npm run db:generate
npm run db:migrate
```
## License
MIT. See `LICENSE` for details.
## GitHub About suggestion
If you want repo metadata to match this README, use this as the GitHub About text:
`AI-powered social media management platform for brands and agencies. Plan, publish, analyze, and collaborate across channels from one workspace.`