Turn one idea into platform-ready social posts without losing your voice.
PostCraft is an AI-assisted social publishing workspace for creators and small teams. It generates several variants from one topic, scores and ranks them, applies reusable brand rules, previews each social format, and can publish now or schedule a post for LinkedIn, X, or a Facebook Page.
Try PostCraft · Read the privacy policy
PostCraft is an active early-stage project. AI generation works with the configured provider keys; social publishing additionally depends on each platform's OAuth approval, scopes, account type, and API availability.
Writing the same idea three times, checking different length constraints, and keeping a consistent voice turns publishing into repetitive work. PostCraft keeps that workflow in one place:
- Enter a topic and choose the target platforms.
- Generate multiple variants through the configured AI providers.
- Compare engagement, clarity, and readability scores.
- Refine the copy under saved brand guardrails and persona preferences.
- Preview the native LinkedIn, X, or Facebook layout.
- Publish immediately or hand the post to Inngest for scheduled delivery.
- Sign in to the live application.
- Complete the profile and brand-voice settings used to ground generation.
- Open the workspace, enter a topic, and select LinkedIn, X, Facebook, or a combination of platforms.
- Generate variants, compare their scores, and edit the selected copy.
- Preview the post in the target platform layout.
- Connect the corresponding social account in Settings.
- Publish immediately or choose a future delivery time.
Open Library to filter completed generations and reuse earlier variants. Open Insights to inspect recorded published and scheduled posts for each connected platform. Trend discovery is available separately and can be run on demand or from saved scheduling preferences.
- Multi-provider generation — uses OpenRouter, Groq, Gemini, and ZhipuAI in a configured fallback order, with support for rotating multiple provider keys.
- Variant ranking — combines heuristic and model-assisted scoring to rank generated hooks, bodies, calls to action, and hashtags.
- Brand controls — stores required rules, blocked language, audience, tone, and profile context in MongoDB-backed workspaces.
- Social previews — renders platform-specific previews and validates copy against the configured LinkedIn, X, and Facebook length targets.
- Publishing and scheduling — publishes through connected OAuth accounts; scheduled work runs through Inngest and is recorded for later inspection.
- Content library and insights — retains completed generations, filters the library, and summarizes published and scheduled activity per platform.
- Trend discovery — collects public topic signals, ranks candidates, and can run manually or on an hourly, daily, or weekly schedule.
- Account recovery — Better Auth supports social sign-in plus email-based verification and password recovery when Resend is configured.
flowchart LR
UI[Next.js workspace] --> API[Route handlers]
API --> Auth[Better Auth]
API --> Domain[Domain services]
Domain --> Mongo[(MongoDB)]
Domain --> AI[AI provider switcher]
Domain --> Queue[Inngest]
Queue --> Social[LinkedIn / X / Facebook APIs]
The App Router owns pages and HTTP boundaries, modules/ contains domain
services and repositories, core/ owns infrastructure such as auth, provider
selection, logging, database access, and queues, and Redux manages shared UI
state.
| Area | Technology |
|---|---|
| Application | Next.js 16, React 19, TypeScript 5 |
| Interface | Tailwind CSS 4, shadcn/ui, Radix UI |
| Client state | Redux Toolkit |
| Data | MongoDB, Mongoose |
| Authentication | Better Auth |
| AI | OpenRouter, Groq, Gemini, ZhipuAI |
| Background jobs | Inngest |
| Resend | |
| Deployment | Vercel |
- Node.js 20.19 or newer
- pnpm
- MongoDB
- At least one configured AI provider;
GEMINI_API_KEYis currently required by the environment schema
git clone https://github.com/montasim/PostCraft.git
cd PostCraft
pnpm install
cp .env.example .env.localReplace the required placeholders in .env.local, then start the services:
pnpm devOpen http://localhost:3000. pnpm dev starts Next.js and the local Inngest
development server together. To work only on the web application, use
pnpm dev:next.
Seeding default personas and guardrails is optional:
pnpm seedKeep secrets server-side and never commit .env.local.
| Variable | Required | Purpose |
|---|---|---|
MONGODB_URI |
Yes | Application, authentication, workspace, and publishing data |
GEMINI_API_KEY |
Yes | Gemini generation and scoring key |
GEMINI_MODEL |
No | Gemini model; defaults to gemini-2.5-flash in .env.example |
GROQ_API_KEY |
No | Groq provider key |
GROQ_MODEL |
No | Groq model name |
OPENROUTER_API_KEY |
No | OpenRouter provider key |
OPENROUTER_MODEL |
No | OpenRouter model name |
OPENROUTER_SITE_URL |
No | Application URL sent with OpenRouter requests |
OPENROUTER_SITE_NAME |
No | Application name sent with OpenRouter requests |
ZAI_API_KEY |
No | ZhipuAI provider key |
ZAI_BASE_URL |
No | ZhipuAI-compatible API base URL |
ZAI_MODEL |
No | ZhipuAI model name |
DEFAULT_AI_PROVIDER |
No | Optional initial provider selection |
INNGEST_EVENT_KEY |
Background work | Inngest event delivery key |
INNGEST_SIGNING_KEY |
Background work | Inngest request-verification key |
APP_URL |
Yes in production | Canonical URL used by auth and metadata |
BETTER_AUTH_SECRET |
Yes | Better Auth signing secret; use a long random value in production |
GOOGLE_CLIENT_ID |
Google login | Google OAuth client ID |
GOOGLE_CLIENT_SECRET |
Google login | Google OAuth client secret |
LINKEDIN_CLIENT_ID |
LinkedIn connection | LinkedIn OAuth client ID |
LINKEDIN_CLIENT_SECRET |
LinkedIn connection | LinkedIn OAuth client secret |
FACEBOOK_CLIENT_ID |
Facebook connection | Facebook OAuth client ID |
FACEBOOK_CLIENT_SECRET |
Facebook connection | Facebook OAuth client secret |
TWITTER_CLIENT_ID |
X connection | X OAuth client ID |
TWITTER_CLIENT_SECRET |
X connection | X OAuth client secret |
RESEND_API_KEY |
Email flows | Resend API key |
EMAIL_FROM |
Email flows | Sender address for authentication email |
LOG_LEVEL |
No | Server log verbosity; defaults to info |
SEED_WORKSPACE_ID |
Seed scripts | Optional workspace ID targeted by seed commands |
NODE_ENV |
No | development, production, or test |
Model names and safe local defaults are documented in
.env.example. Multiple AI keys may be declared with _1,
_2, and later numeric suffixes.
| Command | Purpose |
|---|---|
pnpm dev |
Run Next.js and the Inngest development server |
pnpm dev:next |
Run only the Next.js development server |
pnpm build |
Create a production build |
pnpm start |
Serve the production build |
pnpm lint |
Run ESLint |
pnpm typecheck |
Check TypeScript without emitting files |
pnpm format |
Format TypeScript and TSX files with Prettier |
pnpm seed |
Seed default guardrails and personas |
pnpm seed:guardrails |
Seed only default brand guardrails |
pnpm seed:persona |
Seed only default personas |
pnpm test:ai-limits |
Run the AI quota integration check |
pnpm test:platforms |
Run configured social-platform integration checks |
pnpm clear:accounts |
Delete authentication account records from the configured MongoDB database |
Warning
pnpm clear:accounts is destructive. Confirm MONGODB_URI, back up any data
that must be retained, and never run it casually against production.
The maintained deployment runs on Vercel. A production environment also needs a reachable MongoDB deployment, production OAuth callback URLs, AI provider credentials, and Inngest credentials for background generation and scheduled publishing. Configure every social provider's callback and requested scopes in its own developer console.
- Generated copy and engagement scores are suggestions, not guarantees. Review factual claims and tone before publishing.
- X publishing may require paid API access or available credits. Facebook publishing targets the first Page returned for the connected account, not a personal profile.
- Scheduling depends on the deployed Inngest integration; running only the Next.js process does not provide durable background delivery.
- OAuth tokens and generated content are stored server-side. Use production secrets, HTTPS, least-privilege platform scopes, and an appropriately secured MongoDB deployment.
- Trend sources and third-party APIs can change or rate-limit requests.
app/ Pages and API route handlers
components/features/ Product workflows and platform previews
core/ AI, auth, configuration, database, queue, and logging
modules/ Domain models, repositories, validation, and services
store/ Redux store and UI preferences
scripts/ Seed and integration-check utilities
docs/ Requirements and design references
- Product requirements
- Design system
- Frontend clone specification
- Trending backend implementation notes
- Privacy policy
Bug reports and focused improvements are welcome through GitHub Issues. Please describe the expected behavior, reproduction steps, and the checks you ran. Do not put credentials, OAuth tokens, private generated content, or vulnerability details in a public issue; contact the maintainer through the links on Montasim's GitHub profile for sensitive reports.
The repository does not yet contain dedicated CONTRIBUTING.md, SECURITY.md,
CODE_OF_CONDUCT.md, or SUPPORT.md files. Until those policies are added,
use Issues for public project
discussion and Pull Requests for
reviewable changes.
If PostCraft is useful to you, optional support through SupportKori helps fund hosting and continued maintenance.
PostCraft is independently maintained. Optional SupportKori contributions help cover hosting, AI integration testing, and ongoing maintenance; bug reports, documentation, and code contributions are equally valuable.
This repository does not currently include a license file. Copyright remains with the author, and no open-source license should be assumed.
Built and maintained by Mohammad Montasim Al Mamun Shuvo.