A full-stack school communication and management platform for FCS Innovation Academy.
Read AGENTS.md before making changes. Keep agent workflow and handoff notes out of this README.
- Authentication with Better Auth on Convex and role-based access
- Native Expo mobile app with secure sessions, shared Convex data, and native push
- Announcements, comments, moderation, and notification preferences
- Clubs, channels, invites, membership, and leader/sponsor workflows
- Events, calendar entries, Flex Friday sessions, and student schedules
- Admin user management, audit logging, and demo seed data
| Layer | Technology |
|---|---|
| Web | Next.js 16, React 19, Tailwind CSS, shadcn/ui |
| Mobile | Expo SDK 57, React Native, Expo Router, NativeWind |
| Backend & Database | Convex (Reactive Functions, Database, Search, File Storage) |
| Design | Shared @ia/design-tokens package |
| Tooling | Bun workspaces, Turborepo, EAS |
ia-app/
├── apps/web/ # Next.js 16 web app
├── apps/mobile/ # Expo native mobile app
├── apps/convex/ # Convex backend (schema, functions, auth, storage)
├── packages/design-tokens/ # Shared color, radius, type, and badge tokens
├── docs/ # Current product, architecture, backend, frontend docs
├── AGENTS.md # Agent workflow rules
└── PORTING.md # Historical backend-to-Convex migration context
For a full setup walkthrough, use Getting Started.
Requires Node.js 20.19 or newer and a separately installed Bun executable.
CI uses the Bun version recorded in package.json; local developers may use a
newer compatible Bun release.
git clone https://github.com/FCSIA/ia-app.git
cd ia-app
cp .env.example .env
bun installStart the application (Next.js frontend and Convex dev server in parallel):
bun run devStart the native mobile app with Expo:
bun run dev:mobileThe mobile app has repo-local store assets and production-shaped Expo config. School-owned EAS, Apple, Google, and universal-link values are documented in apps/mobile/STORE_READY.md.
Open Convex dashboard:
bun run --cwd apps/convex convex dash
bun run --cwd apps/convex convex dashboardImportant
Do not run bunx convex dev, npx convex dev, or other Convex commands from the repository root. This monorepo's Convex app lives in apps/convex, so root-level Convex commands can initialize and push an empty convex/ app. Use bun run --filter cvx ... from the root instead.
On a new checkout, initialize its local Convex backend and auth environment:
bun run setup:convex-local
bun run devThe setup command generates BETTER_AUTH_SECRET and defaults SITE_URL only
when they are missing, repairs the local URL pair, and syncs the selected URLs
to the web and mobile apps. Rerunning it preserves existing deployment values.
Browser push also needs VAPID keys. Generate one key pair, put the public key in
apps/web/.env.local, and set the matching Convex deployment values:
bun run --cwd apps/convex web-push generate-vapid-keys
bun run --cwd apps/convex convex env set VAPID_PUBLIC_KEY "<public-key>"
bun run --cwd apps/convex convex env set VAPID_PRIVATE_KEY "<private-key>"
bun run --cwd apps/convex convex env set VAPID_SUBJECT "mailto:admin@example.com"Then seed the small demo profile from the CLI:
bun run --cwd apps/convex convex run --deployment local \
bootstrap:resetAndSeed '{"profile":"development"}'
bun run --cwd apps/convex convex run --deployment local \
bootstrap:seedStatus '{}' --watchIt seeds 50 students and 119 staff. Pass {"profile":"full"} only for the
1,500-student full profile. The Convex Dashboard provides the same internal
functions as an alternative.
bun run dev starts the web and Convex watchers against the selected local
deployment. See Convex Local And Production Runtime
before using a cloud deployment.
Demo seed/reset can also be run from the Convex Dashboard via internal function bootstrap:resetAndSeed.
| Service | URL |
|---|---|
| Web App | http://localhost:3000 |
| Convex Dashboard | https://dashboard.convex.dev (or run bun run db:studio) |
Demo accounts receive random, one-time temporary passwords. After a seed run
completes, use bootstrap:claimSeedCredentials with its run id and store the
output securely. See docs/reference/getting-started.md.
bun run dev # Start web app and Convex dev server in parallel
bun run dev:mobile # Start the Expo mobile app
bun run --cwd apps/convex convex dashboard # Open local/dev Convex Dashboard console
bun run lint # Lint all workspaces
bun run build # Build all workspaces for production
bun run test # Run test suites
bun run fluid:update # Preview updates for every Radix Fluid Functionalism componentFluid component refreshes are intentionally dry-run by default. Preview all components or narrow the report by name:
bun run fluid:update
bun run fluid:update button select tabsWriting requires an explicit component list:
bun run fluid:update -- --write select tabsApp-adapted primitives are protected from automatic replacement because their
public APIs or DOM contracts support existing product behavior. Review and
merge those registry diffs manually. Compound controls using shadcn's addon API
also live separately from Fluid's input-group.
The deployment shape should stay boring and maintainable. Production is modeled as Next.js plus Convex Cloud (data, real-time, and file storage). The app is not a static site.
Full guide: docs/reference/deployment-options.md — Vercel vs Azure hosting options, Convex CI/CD, and scale planning (~1,600 students, few hundred online at peak).
The detailed architecture and feature list starts in docs/architecture/overview.md. Draw production as Next.js → Convex Cloud (not NestJS/PostgreSQL).
Typical choices: Vercel + Convex (simplest ops), or Azure Container Apps + Convex if the frontend must stay in the school Azure subscription.
- CONTRIBUTING.md - Safe student contribution workflow and pull-request checks.
- SECURITY.md - Private vulnerability reporting and testing boundaries.
- docs/reference/getting-started.md — Step-by-step developer environment setup.
- docs/index.md — Current documentation hub.
- docs/architecture/overview.md — Current Convex-era architecture.
- docs/backend/convex-overview.md — Backend function layout and rules.
- docs/frontend/frontend-overview.md — Frontend structure and conventions.
- apps/mobile/README.md - Native mobile setup and verification.
- apps/mobile/STORE_READY.md - External store/EAS/device steps for release.
- PORTING.md — Historical migration context, not the active operating manual.
Public project for FCS Innovation Academy.