Open-source customer feedback platform. Teams collect feature requests on boards, prioritize them in public, publish a roadmap and changelog, and embed the feedback widget in their own product. Agents and scripts reach the same workspace through the Public API and its MCP projection.
Built as a pnpm + Turborepo monorepo with Effect, Drizzle, and TanStack Start. Licensed under the GNU AGPL-3.0.
- Feedback boards with posts, comments, voting, tags, statuses, assignees, and saved views.
- A public roadmap, changelog with RSS, and post pages, with generated Open Graph images.
- An embeddable widget with ESM and UMD builds, React bindings, hub modes, and JWT SSO for signed-in users.
- Workspace insights over 7, 30, or 90 day windows, plus CSV import and export.
- Slack, Discord, GitHub, and signed webhook integrations, with durable outbound delivery and retries.
- A versioned Public API, and the same operations as MCP tools that accept either an API key or OAuth.
- In-app and email notifications, email suppression and bounce handling, and Polar billing.
apps/
server/ Effect HTTP API: RPC, Public API, MCP, integration providers
web/ Dashboard and public portal (TanStack Start, React); Cloudflare or Docker
public-feature-board/ Public portal UI and collections: boards, roadmap, changelog
packages/
auth/ better-auth wiring, organization ACL, API-key plugin
config/ Shared tsconfig base and Effect Config helpers
db/ Drizzle schema, migrations, PGlite test database, seed/nuke
db-migrator/ Standalone migration runner for deployments
domain/ Domain behavior: schemas, repositories, RPC contracts, handlers
domain-contracts/ Schemas and vocabularies both browser and server may import
feedback-widget/ SolidJS iframe widget bundle
id/ Branded identifier types
permissions/ Member permission catalog
post-ui/ Post, comment, and roadmap surface shared by dashboard and portal
rpc-client/ Effect RPC client
sdk/ Published SDK (ESM + UMD)
sdk-react/ Published React bindings for the SDK
transactional/ Email templates and mailer
ui/ Shared UI primitives
utils/ Shared primitives, including runtime type guards
web-shared/ Browser-side shared code: collections, auth context, error parsing
integrations/
core/ Provider registry, delivery worker, credential encryption
webhook/ Signed webhooks
slack/ discord/ Chat providers
github/ Issue tracker provider
tools/ Oxlint plugin and test runners
e2e/ Playwright end-to-end suite
docker/ Local development infrastructure
docs/ Topic docs and docs/adr/ decision records
- Runtime/Server: Node 26, Effect v4,
@effect/platform-node,@effect/sql-pg - Database: PostgreSQL with pgvector via Drizzle ORM; PGlite (
@effect/sql-pglite) for tests - Auth: better-auth, with Polar for billing
- Web: TanStack Start, React 19, TanStack Router/DB/Query/Form, Tailwind v4
- Widget: SolidJS, Vite-built, Floating UI positioning
- State: XState 6
- Observability: OpenTelemetry over OTLP, Sentry for errors, Databuddy for product analytics
- Tooling: pnpm 11, Turborepo, tsrs (a Rust port of TypeScript 7), Oxlint + Oxfmt (type-aware via
@effect/tsgo), Knip, Vitest, Playwright - Infra/Deploy: Docker, Cloudflare via Wrangler
- Node.js
^26.4.0 - pnpm
^11.0.3 - Docker (for local Postgres, Redis, MinIO, and mail) — optional but recommended
-
Install dependencies:
pnpm install
preparerunseffect-tsgo patchhere, which wires the Effect language service into thetsrscompiler and Oxlint. If Effect diagnostics never appear later, that step did not run. -
Copy the environment file and fill in values:
cp .env.example .env
Required configuration includes
DATABASE_URL,AUTH_ENCRYPTION_KEY,APP_URL,API_URL,APP_ROOT_DOMAIN, SMTP settings, and media upload (S3-compatible) settings. See.env.examplefor details. -
Start local infrastructure and run migrations plus seed:
pnpm db:start pnpm db:migrate pnpm db:seed
pnpm db:startbrings updocker/docker-compose.dev.yml: Postgres on 54323, Redis on 63799, Mailpit on 8025/1025, and MinIO on 9001/9002. Those ports are deliberate — they are non-standard so the stack can coexist with a system Postgres or Redis, and.env.exampleis written against them. Do not expect 5432.Both compose files pin the same
container_names, so the dev stack and the production stack indocker-compose.ymlcannot run at once. If you have started the root one,docker compose downfrom the repo root first. -
Run the dev servers (API and web in parallel via Turbo):
pnpm dev
Or run them individually:
pnpm dev:server # API on http://localhost:3000 pnpm dev:web # Dashboard on http://localhost:3001
Public boards answer on workspace subdomains of
APP_ROOT_DOMAIN, such asacme.localhost:3001.
pnpm checkThat runs the toolchain guard, every package's tsrs --noEmit, type-aware Oxlint, the formatter check, and Knip. It needs no database, no build output, and no env file, and CI runs it on every push. Run it before opening a pull request.
AGENTS.md is the repo law: commands, architecture, and the changes that need an owner decision. CONTEXT.md fixes the product's vocabulary. docs/adr/ records why specific boundaries exist. See Documentation for the topic guides.
| Script | Description |
|---|---|
pnpm dev |
Run all dev tasks across the workspace |
pnpm dev:server / pnpm dev:web |
Run the API or the dashboard |
pnpm build |
Build all packages and apps |
pnpm check |
The gate: toolchain, typecheck, lint, format check, and Knip |
pnpm typecheck |
Types only, cached per package |
pnpm knip |
Unused files, dependencies, and exports |
pnpm toolchain |
Check that the Effect and compiler version trains agree |
pnpm test |
Unit tests (@feeblo/e2e excluded) |
pnpm test:e2e |
Playwright end-to-end suite |
pnpm lint / pnpm lint:fix |
Lint and format check / autofix |
pnpm fmt / pnpm fmt:check |
Format / verify formatting only |
pnpm db:start |
Start local Postgres, Redis, Mailpit, and MinIO |
pnpm db:stop / pnpm db:down |
Stop / tear down the local stack |
pnpm db:watch |
Same as db:start, in the foreground |
pnpm db:push |
Push schema to the database |
pnpm db:generate |
Generate SQL migrations from schema changes |
pnpm db:migrate |
Run pending migrations |
pnpm db:seed |
Seed the database with sample data |
pnpm db:studio |
Open Drizzle Studio |
pnpm db:nuke |
Drop and recreate the database |
pnpm db:configure-embeddings |
Set the post embedding vector size (default 1536) |
- Public API and MCP
- Integrations
- Webhooks
- Notifications
- Permissions
- CSV import and export
- Widget SSO
- Telemetry
- i18n
- Architecture decisions
The embeddable SDK lives in packages/sdk and ships ESM + UMD builds, with React bindings in packages/sdk-react. See packages/sdk/README.md and packages/sdk-react/README.md for installation and usage. Release steps are in docs/sdk-releases.md.
Billing uses Polar. Set POLAR_MODE, POLAR_ACCESS_TOKEN, and POLAR_WEBHOOK_SECRET to enable checkout, subscription synchronization, and the customer portal.
Configure the Polar webhook URL as:
https://<API_URL>/api/auth/polar/webhooks
Each recurring product must include metadata that identifies its entitlement plan and billing variant:
{ "plan": "starter", "variant": "monthly" }Supported plan values are starter and professional; supported variants are monthly and yearly. The variant must match the product's recurring interval. Products without valid metadata, archived products, and one-time products are rejected by the checkout API.
After adding the webhook to an existing Polar organization, resend product.created or product.updated events for the current products so the local product catalog is populated before enabling billing.
The workspace a subscription belongs to is the metadata.org value on the checkout, not the Polar customer. Polar resolves a checkout customer by email and allows one customer per email per organization, so a buyer who pays for several workspaces shares one Polar customer and one portal. Deleting an account never deletes a Polar customer for that reason; a deleted workspace's subscription is queued and revoked with retries (see docs/adr/0013 and docs/adr/0014).
Polar also caps a customer at one billable subscription unless the organization enables Settings → Subscriptions → Allow multiple subscriptions. Because the customer is resolved by email, that default caps a buyer across workspaces: a person who already pays for one workspace cannot check out a second one, and Polar refuses on its hosted checkout page after Feeblo has handed the buyer off. Enable the setting on any deployment where one person may pay for more than one workspace; the server logs a warning at startup when the token's organization has it off (see docs/adr/0015).
Production deployments use the Docker images referenced in docker-compose.yml (ghcr.io/g3root/feeblo-server and ghcr.io/g3root/feeblo-web). Images are published automatically to GHCR: pushes to main produce edge and sha-* tags, while version tags produce the release version, major.minor, major, and latest tags. The dashboard can alternatively be deployed to Cloudflare using the Wrangler configuration in apps/web/wrangler.jsonc.
The compose stack uses its own operator file. The development .env is not valid for it: its DATABASE_URL and REDIS_URL point at host ports that do not exist inside the containers.
test -f docker/.env.selfhost || (umask 077 && cp docker/.env.selfhost.example docker/.env.selfhost)
chmod 600 docker/.env.selfhost
$EDITOR docker/.env.selfhost
docker compose --env-file docker/.env.selfhost up -dThe stack expects HTTPS hostnames (the session cookie is Secure), a working SMTP server (account verification sends a code by email), and S3-compatible object storage. See docs/self-hosting.md for DNS and TLS, reverse-proxy trust, OAuth callbacks, public-board subdomains, upgrades, and backups.
The Cloudflare Worker is built from the prod branch, which only ever moves forward to a release tag: run the Promote prod workflow with the tag name (Actions → Promote prod → Run workflow), which checks first and does nothing else while dry run is checked, then run it again with that box cleared to move the branch. From a terminal that is gh workflow run promote-prod.yml -f tag=v1.2.0 -f dry_run=true, then the same command with -f dry_run=false; the tag must have a published Release, because the Docker images are published from that event. prod is never merged into and never force-pushed; see docs/adr/0018.
Production startup enforces two safety checks: AUTH_ENCRYPTION_KEY must be at least 32 bytes, and REDIS_URL must be set so rate limits are shared across server instances.
The Compose database uses the pgvector-enabled PostgreSQL image. Post embeddings default to OpenAI text-embedding-3-small at 1536 dimensions. Set EMBEDDING_API_KEY to enable embeddings; OpenAI-compatible self-hosted providers can also set EMBEDDING_API_URL, EMBEDDING_MODEL, and EMBEDDING_DIMENSIONS.
When changing to a model with a different vector size, reconfigure the database column from the published server image before restarting it:
docker compose --env-file docker/.env.selfhost run --rm server \
node ./migrate/configure-embeddings.js \
--dimensions 768 \
--clear-existingThe command clears incompatible vectors and rebuilds the HNSW index. Omit --clear-existing to make it fail safely when existing vectors would be lost. For a local database, run the same command through pnpm db:configure-embeddings --dimensions 768 --clear-existing.
Copyright © Feeblo contributors. Distributed under the GNU Affero General Public License v3.0.
