Thank you for your interest in contributing to StackAudit! We are building an open-source AI cost intelligence platform designed to bring financial clarity and workload attribution to AI engineering teams.
Whether you are fixing a bug, improving documentation, adding new provider pricing fixtures, or refining unit economics metrics, your help is welcome.
All contributors and participants are expected to adhere to our Code of Conduct. Please treat everyone with respect and kindness.
- Node.js:
22.22.2+andnpm - Docker: Docker Desktop or a running Docker daemon (required for local Supabase)
- Supabase CLI: Automatically available via
npx supabaseafter runningnpm ciinsidestackaudit/
git clone https://github.com/<your-username>/StackAudit-Core.git
cd StackAudit-Core/stackauditnpm ciCopy .env.example to .env.local:
cp .env.example .env.localStart the local Supabase container:
npx supabase startUpdate .env.local with the values printed by npx supabase status:
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
STACKAUDIT_DATABASE_MODE=local
SUPABASE_SERVICE_ROLE_KEY=<service_role_key_from_status>
STACKAUDIT_WORKSPACE_ORG_ID=8a775c7f-e31c-8f9b-9000-000000000001Apply database migrations:
npx supabase db resetLoad reference pricing fixtures and seed deterministic demo data:
npm run setupStart the development server:
npm run devOpen http://localhost:3000 to view your local instance.
To ensure mathematical precision, security, and maintainability across the codebase:
- Never use standard JavaScript floating-point numbers (
number) for financial costs or token rates. - Always use
big.jsfor cost calculations, division, multiplication, and rounding:import Big from "big.js"; const cost = new Big(tokens).div(1_000_000).times(ratePerMillion);
- Store and serialize monetary amounts as exact decimal strings (e.g.,
"12.450000"), never floats.
- The schema is managed exclusively via Supabase migrations in
stackaudit/supabase/migrations/. - Never modify existing or already-committed migration files.
- Always create a new sequential forward migration:
npx supabase migration new <migration_name>
- Keep all aggregation RPCs and queries scoped to the active workspace organization ID.
- Do not add automated third-party provider scraping, background credential storage, or live credential prompts to V0.
- Usage ingestion should adhere to the canonical schema (
CanonicalUsageEvent) via CSV import or sanitized API endpoints. - Maintainers and reviewers will reject changes that introduce hardcoded external credentials or compromise the local-first isolation model.
- Strict TypeScript: Avoid
anytypes; prefer explicit types and Zod validation schemas. - ESLint: Ensure no warnings or errors remain before submitting.
- Component styling: Built on Tailwind CSS and shadcn/ui primitives.
AI coding assistants (e.g. Claude Code, Copilot, ChatGPT, Cursor, Antigravity) are welcomed, provided contributions meet our standard criteria:
- Human Accountability: You remain fully responsible for understanding, explaining, and testing all submitted code.
- Verification: All PRs must include passing tests (
npm testandnpm run test:integrationwhere applicable) and adhere to our financial decimal precision standards (big.js). - Disclosure: In your pull request description, please note if and which AI tools were used during creation.
Before submitting a Pull Request, verify that all test suites pass:
# Inside stackaudit/ directory:
npm run typecheck # Verify TypeScript types
npm run lint # Run ESLint linter
npm test # Run Vitest unit tests
npm run test:integration # Run database integration tests (requires local Supabase running)
npm run build # Verify Next.js production build succeeds- Create a descriptive branch:
feat/add-claude-3-5-haiku-pricingfix/csv-import-timestamp-parsingdocs/clarify-cpo-calculation
- Commit Messages: Follow Conventional Commits:
feat(pricing): add Q4 2024 reference pricing fixturesfix(usage): handle ISO timestamps with timezone offsetsdocs(readme): add troubleshooting section for docker engine
- Open a Pull Request:
- Fill out the provided Pull Request Template.
- Link any related GitHub issues (
Fixes #123). - Include screenshots or terminal output demonstrating your verification.
- Have a question or idea? Open a GitHub Discussion.
- Found a bug? File a detailed report using the Bug Report Template.
- Security concerns? Please follow SECURITY.md for private reporting.