10xbadger

Table of Contents

• Project description
• Tech stack
• Getting started locally
• Available scripts
• Project scope
• Project status
• License

Project description

Badger is a web application (MVP) that replaces legacy Excel and Confluence-based badge tracking with a single system for cataloging badges, submitting badge applications, and building promotion submissions. It focuses on core flows for engineers and administrators: catalog browsing and search, drafting and submitting badge applications, administrative review, promotion building and submission, and basic role-based access via Google Workspace SSO.

See the full Product Requirements Document at /.ai/prd.md.

Tech stack

• Frontend: Astro 5, React 19, TypeScript 5, Tailwind CSS 4, shadcn/ui
• Backend: Supabase (Postgres, auth, SDKs)
• Testing: Vitest (unit/component tests), Playwright (E2E tests)
• AI (optional): Openrouter.ai
• CI/CD & Hosting: GitHub Actions, DigitalOcean (Docker)
• Tooling: pnpm, ESLint, Prettier, Husky, lint-staged

Key package versions (from package.json): astro ^5.14.5, react ^19.2.0, tailwindcss ^4.1.14

Getting started locally

Prerequisites

• Node.js matching .nvmrc (v22.14.0). Use nvm:
  • nvm install 22.14.0
  • nvm use 22.14.0
• pnpm (recommended): npm i -g pnpm
• Supabase project (for full backend functionality)
• Google Workspace admin access (for SSO configuration)

Quickstart

1. Clone the repository:
   • git clone <repo-url>
   • cd 10xbadger
2. Install dependencies:
   • pnpm install
3. Create environment variables
   • The project currently does not include an .env.example. You will likely need:
     • SUPABASE_URL
     • SUPABASE_ANON_KEY (or service role key)
     • OIDC / Google SSO client id / secret
4. Install Playwright browsers (for E2E tests):
   • pnpm exec playwright install chromium
5. Run the dev server:
   • pnpm dev
6. Build for production:
   • pnpm build
7. Preview the production build locally:
   • pnpm preview

Available scripts

Defined in package.json:

Development

• pnpm dev — Run the local development server (Astro)
• pnpm build — Build the production site
• pnpm preview — Preview the production build locally
• pnpm astro — Run the local Astro CLI

Code Quality

• pnpm lint — Run ESLint across the repo
• pnpm lint:fix — Run ESLint with --fix
• pnpm format — Run Prettier to format files

Testing

Unit & Component Tests (Vitest)

• pnpm test — Run unit and component tests
• pnpm test:watch — Run tests in watch mode (for active development)
• pnpm test:ui — Open Vitest UI for visual test management
• pnpm test:coverage — Run tests with coverage report

End-to-End Tests (Playwright)

• pnpm test:e2e — Run E2E tests
• pnpm test:e2e:ui — Run E2E tests with Playwright UI (interactive mode)
• pnpm test:e2e:debug — Debug E2E tests with step-by-step inspector
• pnpm test:e2e:codegen — Generate E2E tests by recording browser interactions
• pnpm test:e2e:report — View the last E2E test report in browser

All Tests

• pnpm test:all — Run all tests (unit, component, and E2E)

Project scope

In-scope (MVP core features)

• Google Workspace SSO (domain-restricted) for authentication and role-based access
• Badge Catalog (CRUD for admins; active-only search/filter)
• Badge Applications (draft, submit, admin review)
• Promotion Templates & Builder (template validation; reservation of badges)
• Reservation & Concurrency handling (optimistic reservation; HTTP 409 structured errors)
• Admin review workflows for badge applications and promotions
• Logging for auth failures and reservation conflicts

Out of scope (MVP)

• Mobile application
• File attachments on badge applications
• Notifications (email/in-app)
• Detailed audit/history and change logs
• Bulk approvals
• Comments / social features
• Automatic import/migration tooling from Excel/Confluence
• Fine-grained admin role hierarchy and multi-tenancy

Project status

• Status: MVP (requirements defined in /.ai/prd.md)
• What exists in repo:
  • Astro-based frontend skeleton with sample components
  • package.json with dev/build/lint/format scripts
  • /.ai/prd.md and /.ai/tech-stack.md documentation
• Next steps / TODOs:
  • Add .env.example and document environment variables
  • Document Supabase DB setup, migrations, and seed scripts
  • Implement Google Workspace SSO setup guide
  • Add CI workflow and deployment docs
  • Add CONTRIBUTING.md and code of conduct

License

This project is licensed under the MIT License — see the LICENSE file for details.