Skip to content

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.

9.1 KB
Raw Blame

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.local and server/.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):

  1. Open your Supabase project dashboard
  2. Go to SQL Editor
  3. For each file in supabase/migrations/ (in alphabetical order — 00001_… first, then 00002_…, 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

  1. Create a branch from main:

    git checkout -b feature/my-feature
    
  2. Make your changes and commit (see commit conventions below).

  3. Verify versions are in sync:

    npm run version:check
    
  4. If 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.sh
    

    Your PR will be labelled needs-migration automatically. 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 under server/src/lib/demo/, or list it in SKIPPED in server/src/lib/demo/coverage.js with the reason. coverage.test.js fails 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 bumps DEMO_VERSION in server/src/lib/demo/index.js, so every demo brand is rebuilt on its next visit.

  5. 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 from web/) checks the format. A new article starts as approved: false.

  6. Push and open a pull request against main.

  7. In your PR description, include:

    • What changed and why
    • How to test the change
    • Screenshots if there are UI changes
  8. 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 lint before submitting
  • Prettier owns formatting. Run yarn format before submitting (or enable format-on-save with the repo's Prettier config). CI runs yarn 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.