CommunityArchitect

Design a complete Discord server from a plain description or a ready-made template, then build it in a real server through the Discord API.

CommunityArchitect is a local tool that designs a complete Discord server from a plain description or a ready-made template, then builds that design in a real server through the Discord API. It runs entirely on your own machine, against your own bot and your own server. There is no hosted backend, no shared API keys, and nothing leaves the computer it runs on.

You describe the community you want ("a competitive Valorant team with weekly scrims", "a med-school study group of about 40 across time zones") and the tool produces a full blueprint: categories, channels, roles, permissions, AutoMod, onboarding, and scheduled events, with a written reason for every choice. You can tweak it, preview exactly what it will do, and then apply it.

What it does differently

The design engine is deterministic and research-backed, not a call out to a model. The same description always produces the same blueprint, and every structural decision traces back to the notes in research/. The applier treats a partly-built or already-built server as a state to reconcile rather than a blank slate, so re-running it is safe and does not create duplicates.

How it works

Three parts share one contract: a versioned JSON document called a ServerSpec, defined in spec/server-schema.json.

1. The generator / brain (src/architect/). It classifies a description into an archetype plus a set of cross-cutting traits, composes a ServerSpec from research-backed building blocks, and validates it. The output is a .json spec plus a .rationale.md design brief explaining the decisions.
2. The applier (src/applier/). It turns a ServerSpec into an ordered list of Discord REST calls and runs them. It is dry-run by default, idempotent, and runs an upfront pre-flight check before touching anything. It has no runtime network dependencies (it uses the built-in fetch).
3. The local web UI (src/ui/). A small studio that wraps the whole flow: a home overview, a template gallery, a live customizer, describe-and-generate, and a gated apply screen. It is a zero-dependency Node server plus a vanilla-JavaScript single-page app (no build step), bound to 127.0.0.1 only.

The UI server imports the same validate, generate, and plan modules the CLI uses, so the two can never drift apart.

Path	What it holds
research/	The knowledge base: feature library and deep dives with citable IDs.
spec/	server-schema.json (the contract) and server-schema.md (Discord API mapping and apply ordering).
src/architect/	Generator: classify, archetype builders, trait modifiers, validation, spec differ.
src/applier/	Applier: plan builder, executor, pre-flight, wipe, role-headroom math, REST client, mock.
src/ui/	Local studio: the server plus the single-page app in public/.
templates/	Ten ready-made designs plus index.json for the gallery.

Installation

Everything runs on your own machine, against your own Discord bot and your own server. You bring your own bot, your own token, and your own server. You are not reusing anyone else's credentials, and every install fills in its own .env that stays on your machine.

1. Clone and install

git clone <your-repo-url> community-architect
cd community-architect
npm install

Requires Node.js 18 or newer (it uses the built-in fetch and has no build step). The only runtime dependency is ajv for spec validation. jsdom is a dev-only dependency used by the UI test.

2. Create your own Discord bot and token

1. Open the Discord Developer Portal at https://discord.com/developers/applications and click New Application.
2. Open the Bot tab, click Reset Token, and copy the token. Treat it like a password. Anyone who has it controls your bot.
3. No privileged gateway intents are required. The applier only makes REST calls to manage the server.

3. Invite the bot to your server

1. In the Developer Portal, open OAuth2, then URL Generator.
2. Select the bot scope. For testing, Administrator is the simplest choice and avoids permission surprises. If you would rather scope it down, the applier needs View Channels, Send Messages, Manage Messages, Manage Channels, Manage Roles, Manage Server, Manage Webhooks, and Manage Events. The pre-flight check reports anything missing before it changes anything.
3. Open the generated URL and add the bot to a server you own or administer. Use a throwaway server for your first runs.
4. In Server Settings, then Roles, drag the bot's own role to the top of the list (or at least above any role it will create). A bot cannot raise its own role, so if a blueprint defines many roles you have to make this room yourself. See Troubleshooting for why this matters.

4. Add your credentials

cp .env.example .env

Edit .env and set:

• DISCORD_BOT_TOKEN: the token from step 2.
• DISCORD_GUILD_ID: the numeric ID of your server. Enable Developer Mode in Discord (Settings, then Advanced), then right-click the server icon and choose Copy Server ID.

.env is gitignored and must never be committed. This is your own bot and your own server, so only you fill it in. You are now ready to run it.

Running it

Web UI (the easiest place to start)

npm run ui

Open http://127.0.0.1:7700. You can browse and customize templates, generate a design from a description, and preview the exact apply plan with no token at all. Everything except the live apply works fully offline. The apply button only unlocks after you paste your own bot token and guild ID and retype the guild ID to confirm.

Command line

Generate a design from a description:

npm run architect -- "a cozy book club for about 50 people" --out out/book-club

Preview the apply plan without touching Discord (this is the default, no token needed):

node src/applier/index.js out/book-club.json

Apply for real (reads the token and guild ID from .env):

node src/applier/index.js out/book-club.json --execute --report-dir out/apply

--report-dir is where the run report and manual checklist are written. It is optional in dry-run and recommended with --execute.

Reset a throwaway server (read the safety notes before using this):

node src/applier/index.js --wipe --guild <your-guild-id> \
  --confirm-guild <your-guild-id> --wipe-roles --reset-settings \
  --report-dir out/wipe

Tests

npm test

All tests run offline against an in-memory mock of the Discord API, plus a jsdom run of the UI. No network calls are made.

Use it from Claude Code (plugin)

CommunityArchitect also ships as a Claude Code plugin, so you can drive the whole flow (generate from a description, pick a template, dry-run the plan, and a gated live apply) from inside your own Claude Code session, on your own subscription. It still runs locally, on your own machine, with your own bot and your own server. There is no hosted or web version.

Install it from this repository (you need access to the repo):

/plugin marketplace add jakeefr/community-architect
/plugin install community-architect@community-architect

Then invoke the skill. It also loads automatically when you ask Claude to design a Discord server:

/community-architect:architect a competitive Valorant team with weekly scrims

The skill surfaces the role-headroom prerequisite up front (a bot cannot raise its own role), runs the dry-run by default, and applies for real only after you confirm and provide your own credentials. It reads DISCORD_BOT_TOKEN and DISCORD_GUILD_ID from your environment or a .env file, exactly like the CLI. Node.js 18 or newer must be installed; the skill runs npm install in the plugin directory on first use.

To work on the plugin locally without installing, run claude --plugin-dir . from a clone, or validate it with claude plugin validate ..

Safety model

The applier is built to fail safe and to be re-run without fear.

• Dry-run by default. Nothing touches Discord unless you pass --execute. The default output is the full ordered plan plus the manual checklist.
• Pre-flight check. Before any change, a read-only pass reports every blocker at once (bot not in the guild, missing permissions, not enough role headroom, missing Community prerequisites) instead of failing partway through.
• Idempotent re-runs. A second apply of the same spec reuses everything that already exists (roles, channels, AutoMod rules, webhooks, pinned messages) instead of creating duplicates. If a run aborts, fix the cause and re-run.
• Wipe guardrails. The wipe command refuses unless --confirm-guild exactly matches the target, prints the full delete plan first, and then requires either --yes or retyping the guild ID. The @everyone role and all managed or integration roles are never deleted. Roles are only removed if you pass --wipe-roles. A guild with more than 25 members is refused outright, on the assumption that it is a real community rather than a test server.
• Token handling. Tokens are read from .env for the command line, or pasted into the local UI and used only for that request. They are never written to disk by the tool and never logged.

A note on run reports: the files written by --execute and --wipe (apply-report.json, wipe-report.json, and the manual checklist) contain real channel and role IDs, and any webhook URLs they create include secret tokens. The default report locations (out/ and apply-output/) are gitignored. If you point --report-dir somewhere else, keep it out of version control.

Manual steps the API cannot do

Some things Discord does not expose to bots, or restricts to the server owner. The applier never drops these silently. It collects them into a manual-checklist.md so you have a single to-do list after applying:

• Custom expressions. Uploaded emoji, stickers, and sounds. The generator writes a creative brief for each, but you upload the art yourself in Server Settings, then Emoji.
• Inviting other bots and integrations. A bot cannot install another bot, so any suggested integrations are listed for you to invite, along with the permissions they need.
• Owner-only settings. Things like requiring 2FA for moderators, enabling raid protection and CAPTCHA, rules screening, and Server Subscriptions or other monetization.
• Boost-gated branding. The server banner, invite splash, vanity invite URL, server tag, and role icons, which unlock at specific boost levels. Each comes with a creative brief.

Note on forum channels: the applier does set forum tags and unicode default reactions automatically through the API (available_tags and default_reaction_emoji). The one case that becomes manual is a forum whose default reaction is a custom uploaded emoji, since the emoji has to exist before it can be referenced. Upload the emoji first, then set the reaction.

Troubleshooting

The bot cannot create or position a role. This is the most common first-run snag. A bot can never create or move a role above its own highest role. If the bot's role sits below where a new role needs to go, the apply fails. Fix it in Server Settings, then Roles, by dragging the bot's role above the roles it will manage (the top of the list is safest). The pre-flight check reports this before any change is made, so a clean pre-flight means you have enough headroom.

Project status

The generator, the applier, and the UI are complete and covered by offline tests. It runs from a cloned checkout or as a Claude Code plugin (see the sections above); it is not published to npm. Reading an existing live server and diffing it against a spec is the next planned step (the spec differ and the idempotent reuse logic are the groundwork for it). See CHANGELOG.md for recent work and SESSION_NOTES.md for notes on real Discord API behavior.

Contributing

Contributions are welcome. See CONTRIBUTING.md for local setup, running the offline tests, the SESSION_NOTES.md precedence rule for anyone touching Discord API behavior, and how to open a pull request. Bug reports and feature requests use the GitHub issue templates.

License

Released under the MIT License. You bring your own bot, token, and server; the license covers this tool, not your Discord credentials or content.