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–012/ # 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) |
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 |
| 007 | Mock Authentication | P1 | Implemented |
| 007 | Simple UI Pages | P0 | Implemented |
| 008 | Cross-Platform UI | P0 | Implemented (web) |
| 009 | User Directory | P1 | Implemented |
| 010 | Events Explorer | P1 | Implemented |
| 011 | Azure Deployment | P1 | Specified |
| 012 | Managed Identity Deploy | P2 | Specified |
| 013 | Platform Improvements | P2 | Draft |
Specs 006 and 007 are internal infrastructure (security hardening, dev tooling, UI pages). Spec 008 mobile phases are deferred. Specs 011–012 cover Azure production deployment and are specified but not yet fully deployed. Spec 013 captures documentation gaps and remaining task triage identified during repository review.
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 extractable; locale-aware formatting
- 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 (339 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.