Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.
Contributing to Ansvisor
Thank you for your interest in contributing to Ansvisor! This guide will help you get started.
Ways to Contribute
- Bug reports — found something broken? Open an issue.
- Feature requests — have an idea? Start a discussion or open an issue.
- Code contributions — fix a bug or implement a feature via pull request.
- Store connectors — bring a store's or marketplace's products into the catalog; see CONNECTORS.md.
- Documentation — improve guides, fix typos, add examples.
Prerequisites
- Node.js >= 20
- A Supabase project (URL + anon key)
- At least one AI provider API key (OpenAI, Google Gemini, Anthropic, Perplexity, or Grok)
- Docker + Docker Compose (optional, for containerized setup)
Project Structure
ansvisor/
├── web/ # Next.js 16 frontend (TypeScript)
├── server/ # Express backend (Node.js ESM)
├── supabase/ # Database migrations and config
├── help/ # Product Help articles Chat answers from (help/README.md)
├── scripts/ # Version management tooling
├── docker-compose.yml # Containerized deployment
├── CHANGELOG.md
└── LICENSE
Both web/ and server/ are independent packages with their own package.json and Dockerfile. They share a unified version number managed from the root.
Development Setup
1. Fork the repository
Click the Fork button on github.com/ansvisor/ansvisor to create your own copy.
2. Clone your fork
Replace YOUR_USERNAME with your GitHub username:
git clone https://github.com/YOUR_USERNAME/ansvisor.git
cd ansvisor
3. Add upstream remote (recommended)
This allows you to sync with the main repo:
git remote add upstream https://github.com/ansvisor/ansvisor.git
4. Configure environment variables
cp web/.env.example web/.env.local
cp server/.env.example server/.env
Fill in at minimum:
- Supabase URL and anon key (both
web/.env.localandserver/.env) - At least one AI API key in
server/.env(e.g.OPENAI_API_KEY)
5. Set up the database
Run the migration SQL to create all tables, indexes, RLS policies, and triggers in your Supabase project:
Option A — Supabase SQL Editor (easiest):
- Open your Supabase project dashboard
- Go to SQL Editor
- For each file in
supabase/migrations/(in alphabetical order —00001_…first, then00002_…, etc.), paste its contents and click Run
Option B — Supabase CLI:
npx supabase link --project-ref <YOUR_PROJECT_REF>
npx supabase db push
Demo data (optional)
For a pre-populated local dashboard, the repo ships supabase/seed.sql — an idempotent fixture (one demo organization, brand, topics, prompts, ~120 prompt results across all tracked engines, prompt search volumes, competitors, content opportunities with source data, and AI traffic logs). The Supabase CLI loads it on:
npx supabase db reset
Sign in with [email protected] / demo123 to land on a populated dashboard.
Heads-up: the Prompts and Content pages fetch through the backend API (
server/), not Supabase directly. Start both dev servers (step 7) — otherwise those two pages show a "Failed to load" toast even though the data is seeded. The seed runs only against a local Supabase via the CLI; hosted/production projects are never touched by it.
6. Install dependencies
The web app uses yarn, the server uses npm:
cd web && yarn install
cd ../server && npm install
7. Start dev servers
In separate terminals:
# Terminal 1 — frontend (http://localhost:3000)
cd web && yarn dev
# Terminal 2 — backend (http://localhost:80)
cd server && npm run dev
Docker alternative
If you prefer Docker, configure your .env files first, then:
docker compose up --build
Branch Naming
We follow GitHub Flow with a single main branch. Create short-lived branches from main using these prefixes:
| Prefix | Purpose | Example |
|---|---|---|
feature/ |
New feature | feature/competitor-export |
fix/ |
Bug fix | fix/tracking-timeout |
chore/ |
Maintenance | chore/update-deps |
docs/ |
Documentation | docs/setup-guide |
Making Changes
Create a branch from
main:git checkout -b feature/my-featureMake your changes and commit (see commit conventions below).
Verify versions are in sync:
npm run version:checkIf you added or edited a file under
supabase/migrations/, regenerate the consolidated schema and commit the result — CI fails if it is out of date:bash supabase/build-schema.shYour PR will be labelled
needs-migrationautomatically. That label is a reminder for the maintainer merging it: the file is only half of a migration, and the other half is applying it to the hosted database. You do not need to do anything about the label yourself.If the migration adds a table with a
brand_id, say what the demo brand shows for it: build its rows in a module underserver/src/lib/demo/, or list it inSKIPPEDinserver/src/lib/demo/coverage.jswith the reason.coverage.test.jsfails until you do. A change to what the demo's data looks like (a module's rows, or a column a page reads from them) also bumpsDEMO_VERSIONinserver/src/lib/demo/index.js, so every demo brand is rebuilt on its next visit.If your change alters what a user sees or does, add or update its Help article under
help/in the same pull request ("Help article updated"): one article per page, feature, setting and main task, in the format of help/README.md.yarn test(run fromweb/) checks the format. A new article starts asapproved: false.Push and open a pull request against
main.In your PR description, include:
- What changed and why
- How to test the change
- Screenshots if there are UI changes
Wait for review, address feedback, and your PR will be merged.
Checking for schema drift
A migration that was committed but never applied leaves the database missing something the code calls, which surfaces as a runtime error rather than a failing build. To check a database against what this repo expects:
bash supabase/check-drift.sh # prints SQL; paste it into the SQL Editor
It reads the repo and writes a read-only query — no credentials, no connection, nothing written. An empty result means no drift; any row is something the code expects and that database does not have. Worth running after applying a migration, and after pulling a batch of merged changes.
Commit Messages
We use Conventional Commits:
<type>: <description>
Types:
| Type | When to use |
|---|---|
feat |
New feature |
fix |
Bug fix |
chore |
Maintenance, dependency updates |
docs |
Documentation only |
refactor |
Code change that neither fixes a bug nor adds a feature |
test |
Adding or updating tests |
Examples:
feat: add competitor export endpoint
fix: resolve tracking timeout on large datasets
chore: update AI SDK to v6.1
docs: add self-hosting guide
Scope is optional but helpful for monorepo clarity:
feat(server): add rate limiting to tracking API
fix(web): correct chart rendering on mobile
Code Style
Web (web/)
- TypeScript with strict mode enabled
- ESLint with
eslint-config-next(core-web-vitals + typescript) - Run
yarn lintbefore submitting - Prettier owns formatting. Run
yarn formatbefore submitting (or enable format-on-save with the repo's Prettier config). CI runsyarn format:check, so unformatted code will fail the check — don't hand-format or reformat unrelated lines.
Server (server/)
- Node.js with ES modules (
"type": "module") - Zod for runtime validation
- Follow existing patterns in
src/
General
- Follow the conventions already present in the codebase
- Keep changes focused — one concern per PR
Versioning
All three package.json files (root, web/, server/) share the same version. Use the provided scripts to manage versions:
# Check that all versions match
npm run version:check
# Bump version (updates all three package.json files)
npm run version:bump -- patch # 0.1.0 → 0.1.1
npm run version:bump -- minor # 0.1.0 → 0.2.0
npm run version:bump -- major # 0.1.0 → 1.0.0
Do not edit version numbers in package.json files manually.
Reporting Issues
When opening an issue, please include:
- Bug reports: Steps to reproduce, expected vs. actual behavior, Node.js version, browser (if applicable)
- Feature requests: Use case description and why it would be useful
License
By contributing to Ansvisor, you agree that your contributions will be licensed under the MIT License.