A full-stack community events platform built entirely through agentic AI development using Spec-Kit. This repository serves as a reference implementation demonstrating how AI agents can ship production-quality software when guided by rigorous specifications and architectural principles.
AcroYoga Community connects practitioners with local events, teachers, and each other. Core capabilities:
- Event Discovery & RSVP — Browse, filter, and RSVP to events with role selection (Base/Flyer/Hybrid), waitlist support, and calendar sync
- Community & Social — Follow users, threaded discussions, interest-based connections, content moderation and blocking
- Recurring & Multi-Day Events — RRule-based recurrence, multi-day festivals, per-occurrence overrides
- Permissions & Creator Accounts — Hierarchical role-based access scoped to geographic regions (city → country → global)
- Teacher Profiles & Reviews — Verified instructor profiles, certification tracking, ratings and reviews
- Payments & Bookings — Stripe Connect for creator payouts, concession pricing, credits, and refund policies
- User Directory — Browse, search, and filter community members with relationship status, proximity sort, social link icons, and profile completeness
- Cross-Platform UI — Shared design token pipeline (CSS, TS, Swift, Kotlin) with 17 reusable components and Storybook 10 component explorer
- Events Explorer — Interactive map, calendar, and location tree for advanced event discovery with synchronized filtering
- Azure Deployment — Production deployment on Azure Container Apps with Managed Identity, Front Door CDN, and automated CI/CD
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router, React 19, Server Components, proxy.ts) |
| Language | TypeScript 5.9 (strict mode) |
| Styling | Tailwind CSS 4 |
| Database | PostgreSQL (node-pg) with raw SQL migrations |
| Auth | NextAuth.js v5 (mock auth for development) |
| Payments | Stripe + Stripe Connect |
| Validation | Zod 4 at every API boundary |
| Testing | Vitest 4 + PGlite (in-memory Postgres) |
| Components | Storybook 10 with @storybook/react-vite |
| Storage | Azure Blob Storage (media uploads with EXIF stripping) |
| Recurrence | rrule for iCal-compliant scheduling |
This is an npm workspaces monorepo with shared packages:
├── apps/
│ └── web/ # Next.js 16 web application
│ ├── src/app/ # App Router pages & API routes
│ ├── src/components/ # Web-specific components
│ ├── src/db/ # SQL migrations & seeds
│ ├── src/lib/ # Business logic by domain (20+ modules)
│ ├── .storybook/ # Storybook 10 config
│ └── tests/ # Integration tests (PGlite)
│
├── packages/
│ ├── shared/ # Cross-platform types & utilities
│ │ └── src/types/ # Shared TypeScript interfaces
│ ├── shared-ui/ # Cross-platform UI components (15 components)
│ │ └── src/ # 5-file pattern per component
│ └── tokens/ # Design token pipeline
│ ├── src/ # Token definitions (JSON, W3C DTCG format)
│ └── build/ # Generated CSS, TS, Swift, Kotlin
│
├── specs/ # Spec-Kit feature specifications
│ ├── constitution.md # Architectural principles (v1.5.0)
│ └── 001–016/ # Feature specs with plans, tasks, contracts
│
└── .agent.md # UI Expert agent configuration
| Workspace | Package | Description |
|---|---|---|
apps/web |
@acroyoga/web |
Next.js 16 web app (App Router, React 19, Turbopack) |
packages/shared |
@acroyoga/shared |
Shared types and contracts |
packages/shared-ui |
@acroyoga/shared-ui |
17 cross-platform UI components with design tokens |
packages/tokens |
@acroyoga/tokens |
Design token pipeline (CSS, TS, Swift, Kotlin output) |
apps/mobile |
@acroyoga/mobile |
Expo/React Native mobile app |
Each feature is developed from a full spec (user scenarios, data model, API contracts, implementation plan, and tasks). All specs live in specs/:
| Spec | Name | Priority | Status |
|---|---|---|---|
| 001 | Event Discovery & RSVP | P0 | Implemented |
| 002 | Community & Social | P1 | Implemented |
| 003 | Recurring & Multi-Day Events | P1 | Implemented |
| 004 | Permissions & Creator Accounts | P0 | Implemented |
| 005 | Teacher Profiles & Reviews | P1 | Implemented |
| 006 | Code Review Fixes | P0 | Implemented |
| 007a | Mock Authentication | P1 | Implemented |
| 007b | Simple UI Pages | P0 | Implemented |
| 008 | Cross-Platform UI | P0 | Implemented (web) |
| 009 | User Directory | P1 | Implemented |
| 010 | Events Explorer | P1 | Implemented |
| 011a | Azure Deployment | P1 | Implemented |
| 011b | Entra External ID | P1 | Implemented |
| 012 | Managed Identity Deploy | P2 | Implemented |
| 013 | Platform Improvements | P2 | Complete |
| 014 | Internationalisation | P1 | Implemented |
| 015 | Background Jobs & Notifications | P1 | Implemented |
| 016 | Mobile App (Expo/React Native) | P1 | Implemented |
Specs 006 and 007 are internal infrastructure (security hardening, dev tooling, UI pages). Specs 011–012 cover Azure production deployment with Managed Identity and Entra External ID social login. Spec 013 added CONTRIBUTING.md, API reference docs, database/testing docs, Playwright E2E tests, and triaged all remaining tasks across specs 001–010. Specs 014–016 are the next wave of features — i18n (Constitution VIII), background jobs & notifications (Constitution X), and native mobile apps completing the cross-platform vision from Spec 008.
The platform is feature-complete for web. All P0 and P1 features are implemented across 13 specs (001–013). The next wave of work is captured in three new specs:
| Priority | Spec | Scope | Tasks |
|---|---|---|---|
| Next | 014 — Internationalisation | next-intl integration, string extraction (~200+ strings), Intl.DateTimeFormat migration, RTL support, locale switcher, CI enforcement |
44 tasks, 6 phases |
| Next | 015 — Background Jobs & Notifications | pg-boss job queue, in-app notifications, email delivery (Azure Communication Services), notification preferences, scheduled jobs (review reminders, cert-expiry) |
45 tasks, 7 phases |
| Future | 016 — Mobile App | Expo/React Native, 5-tab navigation, JWT auth, TanStack Query + MMKV offline, push notifications. Completes Spec 008's deferred mobile phases | 63 tasks, 10 phases |
Additional deferred work (lower priority, not yet specced):
- UI Component Extraction — 21 presentational component wrappers (Spec 001 deferred tasks)
- Performance Optimization — Image optimization, lazy loading, skeleton loaders
- WCAG Manual Audit — Keyboard navigation and screen reader testing beyond axe-core automation
- SEO & Social Sharing — OG metadata generation, event sharing cards
- Geolocation & Heatmap — "Near Me" button and event density heatmap (Spec 010 deferred)
- Contributing Guide — Setup, workflow, conventions, and quality gates
- API Reference — All 92 API endpoints with auth requirements
- Database Schema — 39 tables, relationships, and migration process
- Testing Guide — PGlite setup, test patterns, and coverage areas
- Deployment Runbook — Azure deployment procedures
- Environment Setup — Environment variables and configuration
The project is governed by a constitution (v1.5.0) defining 14 core principles:
- API-First Design — Every feature exposes a versioned REST API before any UI
- Test-First Development — Integration tests against real (in-memory) Postgres; ≥80% service coverage
- Privacy & Data Protection — GDPR-compliant export/deletion; PII encrypted at rest; EXIF stripping
- Server-Side Authority — All business rules enforced server-side; Zod validation at boundaries
- UX Consistency — WCAG 2.1 AA; mobile-first; shared design tokens
- Performance Budget — LCP <2.5s; initial JS <200KB; no N+1 queries
- Simplicity — No premature abstraction; dependencies justified in PRs
- Internationalisation — All strings in
apps/web/messages/*.json;next-intllocale switching;Intl.DateTimeFormat/Intl.NumberFormatformatting; RTL structural support; CI-blocking lint - Scoped Permissions — Geographic RBAC with
withPermission()middleware - Notification Architecture — Multi-channel, user-configurable, async delivery
- Resource Ownership — Every mutation verifies caller is owner or scoped admin
- Financial Integrity — Server-side pricing; Stripe Connect; signed OAuth state
- Codespaces Mandate — All development runs in GitHub Codespaces
- Managed Identity — Azure Managed Identity with DefaultAzureCredential for all service connections
- Node.js 22+ (managed via fnm)
- PostgreSQL 15+ (or use PGlite for development/testing)
- GitHub Codespaces (recommended) or a Linux environment — ensures local–CI parity
npm install
npm run tokens:build # Generate design tokens (CSS, TS, Swift, Kotlin)npm run dev # Concurrent: tokens watch + Next.js dev server
npm run build # tokens:build → Next.js production build
npm run test # tokens → shared-ui → web test suite
npm run storybook # Storybook 10 component explorer
npm run lint # ESLint (includes jsx-a11y)npm run test -w @acroyoga/tokens # Run token pipeline tests (20 tests)
npm run test -w @acroyoga/shared-ui # Run shared-ui component tests (85 tests)
npm run test -w @acroyoga/web # Run web integration tests (630+ tests)
npm run tokens:build # Rebuild design tokens
npm run tokens:watch # Watch token source & rebuild on changeEvery PR must pass before merge:
tsc --noEmit— zero type errorsvitest run— all tests pass, no skipped tests without a linked issue- ESLint — zero warnings (warnings are errors)
- Production build completes
- Bundle size ≤200 KB compressed
- No new axe-core accessibility violations
- API changes update the central types file with corresponding tests
- Constitution compliance confirmed by reviewer
- Permission smoke test for every new mutation endpoint (403 for unauthorized callers)
- Auth consistency — session-based only, no client-injectable headers
This project was developed using the Spec-Kit agentic workflow:
- Constitution — Define architectural principles and quality gates
- Specify — Write detailed feature specs with user scenarios (Given/When/Then)
- Plan — Generate implementation plans with data models and API contracts
- Tasks — Break plans into dependency-ordered, actionable tasks
- Implement — AI agents execute tasks following the spec and constitution
Each feature lives in specs/NNN-feature-name/ with its own spec, plan, tasks, data model, research notes, and API contracts.
See SECURITY.md for reporting vulnerabilities.