Development Commands

pnpm dev          # Start Next.js dev server
pnpm build        # Production build
pnpm lint         # ESLint
pnpm typecheck    # TypeScript type checking
pnpm format       # Prettier formatting

Project Structure

superteam-academy/
├── apps/
│   ├── web/                    # Next.js 14 application
│   │   ├── src/app/            #   App Router pages ([locale] route groups)
│   │   │   ├── [locale]/
│   │   │   │   ├── (marketing)/  # Landing page
│   │   │   │   ├── (platform)/   # Authenticated routes (dashboard, courses, etc.)
│   │   │   │   └── admin/        # Admin panel
│   │   │   └── api/              # API routes (auth, lessons, achievements, etc.)
│   │   ├── src/components/     #   UI components (auth, editor, gamification, layout)
│   │   ├── src/lib/            #   Utilities (supabase, sanity, solana, analytics)
│   │   └── src/messages/       #   i18n translation files (en, pt-BR, es)
│   └── build-server/           # Rust/Axum build server (GCP Cloud Run)
├── onchain-academy/            # Anchor workspace (Solana program)
│   ├── programs/               #   On-chain program source (Rust)
│   └── tests/                  #   Integration + unit tests
├── packages/
│   ├── types/                  # Shared TypeScript interfaces
│   ├── deploy/                 # Browser-based Solana program deployment library
│   └── config/                 # Shared ESLint, TS, Tailwind configs
├── sanity/                     # Sanity Studio + schemas + seed data
├── supabase/                   # Database schema + migrations
├── scripts/                    # Helper scripts (init-program, update-program-id)
├── wallets/                    # Keypairs (gitignored)
└── docs/                       # Documentation

Environment Variables

Copy .env.example to apps/web/.env.local and fill in values.

Supabase (Required)

| Variable | Scope | Description | | ------------------------------- | ------ | ------------------------------------------------------------------- | | NEXTPUBLICSUPABASE_URL | Client | Supabase project URL | | NEXTPUBLICSUPABASEANONKEY | Client | Public anon key (safe for browser) | | SUPABASESERVICEROLE_KEY | Server | Service role key for admin operations. Never expose to browser. |

Sanity CMS (Required)

| Variable | Scope | Description | | ------------------------------- | ------ | ------------------------------------------------------------ | | NEXTPUBLICSANITYPROJECTID | Client | Project ID from sanity.io/manage | | NEXTPUBLICSANITY_DATASET | Client | Dataset name (usually production) | | SANITYAPITOKEN | Server | Editor token for seed import script only |

Solana (Required for on-chain features)

| Variable | Scope | Description | | ----------------------------- | ------ | ------------------------------------------------------- | | NEXTPUBLICSOLANARPCURL | Client | RPC endpoint (default: https://api.devnet.solana.com) | | NEXTPUBLICSOLANA_NETWORK | Client | Network name (devnet) | | NEXTPUBLICPROGRAM_ID | Client | Program ID from anchor deploy | | NEXTPUBLICXPMINTADDRESS | Client | XP mint pubkey from initialize output |

Admin / Signing (Required for admin panel and on-chain operations)

| Variable | Scope | Description | | -------------------------- | ------ | ------------------------------------------------------------------------------------------------ | | PROGRAMAUTHORITYSECRET | Server | JSON array of authority keypair bytes (64 elements). The keypair that signed initialize. | | BACKENDSIGNERSECRET | Server | JSON array of backend signer keypair bytes. On devnet, same as PROGRAMAUTHORITYSECRET. | | XPMINTAUTHORITY_SECRET | Server | JSON array of XP mint authority keypair bytes. Signs XP token mints; omit to disable XP minting. | | ADMIN_SECRET | Server | Admin panel password (min 32 chars, random string) | | SANITYADMINTOKEN | Server | Write-enabled Sanity API token for course sync in admin panel |

Build Server (Optional -- for code compilation features)

| Variable | Scope | Description | | ---------------------- | ------ | -------------------------------------------------------------------------------- | | BUILDSERVERURL | Server | Cloud Run service URL | | BUILDSERVERAPIKEY | Server | API key for X-API-Key header (same as ACADEMYAPI_KEY on Cloud Run) | | RUSTPLAYGROUNDURL | Server | Upstream for /api/rust/execute (default: https://play.rust-lang.org/execute) |

AI Lesson Assistant (Optional)

| Variable | Scope | Description | | ---------------- | ------ | -------------------------------------------------------------- | | GEMINIAPIKEY | Server | Google Gemini API key for the in-lesson AI chat/suggest routes |

Analytics (Optional -- platform works without these)

| Variable | Scope | Description | | -------------------------------- | ------ | ---------------------------------------------------------- | | NEXTPUBLICGA4MEASUREMENTID | Client | Google Analytics 4 measurement ID | | NEXTPUBLICPOSTHOG_KEY | Client | PostHog project key | | NEXTPUBLICPOSTHOG_HOST | Client | PostHog instance URL (default: https://us.i.posthog.com) | | NEXTPUBLICSENTRY_DSN | Client | Sentry error tracking DSN (public/safe to expose) |

App URL

| Variable | Scope | Description | | --------------------- | ------ | ---------------------------------------------------------------------------------- | | NEXTPUBLICAPP_URL | Client | Base URL for sitemap, OG tags, NFT metadata URI (default: http://localhost:3000) |

Deployment

Superteam Academy deploys as a Vercel-hosted Next.js app backed by Supabase (Postgres + Auth), Sanity CMS, and a Solana on-chain program.

• Production Deployment Guide -- Full instructions for Vercel, Supabase, Sanity, Google OAuth, GCP Cloud Run (build server), analytics, custom domains, and post-deployment checklist.
• Program Deployment Guide -- On-chain program build, deploy, and initialize workflow (keypair generation, Anchor build, devnet deploy, XP mint creation).

On-Chain Program

Program: Superteam Academy (onchain_academy) Network: Solana Devnet Program ID: 7NeJaSRyb4Wxay3Tcd9bdpD7T3GWYUQSFyrhG8SgwE8V

The program manages the full learning lifecycle on-chain:

• 16 instructions: initialize, create/update/close course, enroll, complete lesson, finalize course, issue/upgrade credential, create achievement type, unlock achievement, register/revoke minter, update config, unenroll, and more
• 6 PDA account types: Config, Course, Enrollment, MinterRole, AchievementType, AchievementRecord
• XP minting: Token-2022 soulbound tokens minted on lesson completion
• Credential issuance: Metaplex Core NFTs minted on course completion

Admin Panel

URL: /{locale}/admin (e.g., /en/admin) Auth: Enter the ADMIN_SECRET environment variable value

The admin panel bridges Sanity CMS content with the on-chain program:

• Deploy courses: Creates the course on-chain, creates a Metaplex Core collection for the track, and syncs onChainStatus back to Sanity
• Deploy achievements: Creates achievement types on-chain with their Metaplex Core collections
• View sync status: See which courses and achievements are deployed on-chain

Documentation

| Document | Description | | -------------------------------------------- | ----------------------------------------------------- | | Architecture | System design, account maps, data flows, CU budgets | | CMS Guide | Sanity schema, GROQ patterns, content workflow | | Customization | Theming, i18n, gamification, and extending | | Admin Guide | Admin panel usage and course/achievement deployment | | Program Deployment | On-chain program build, deploy, and initialize | | Developer Reference | Full codebase conventions, security model, API routes |

Known Limitations / Roadmap

The on-chain program is feature-complete with 16 instructions covering the full learning lifecycle. The following items are scoped for future iterations:

• Track collection enforcement: track_collection is validated server-side during credential issuance but is not yet enforced on-chain as an account constraint (future program upgrade).
• Cross-course achievements: Three achievement types (Anchor Expert, Full Stack Solana, Rust Rookie) have partial frontend logic but lack proper cross-course tracking infrastructure. full-stack-solana is hardcoded to false; anchor-expert and rust-rookie use lesson ID pattern matching instead of course-level completion checks.
• Build server: Compilation features (buildable Rust challenges + program deployment) require a separately deployed Rust/Axum build server on GCP Cloud Run. See the Deployment section for setup details.

Code Quality

• TypeScript strict mode with zero any types
• ESLint + Prettier enforced via Husky pre-commit hooks
• Conventional commits: feat:, fix:, docs:, chore:, refactor:
• All UI strings externalized via next-intl (never hardcoded)
• Server components by default, client components only when needed
• RLS enabled on all Supabase tables; sensitive functions restricted to service_role

Contributing

• Fork the repository
• Create a feature branch: git checkout -b feat/your-feature
• Commit using conventional commits: git commit -m "feat: add quiz lesson type"
• Push and open a pull request

License

MIT

Acknowledgments

• Superteam Brazil -- community and bounty program
• Solana Foundation -- blockchain infrastructure
• Built with Claude Code (Anthropic)