Asymmetric.al - Kingdom Impact Platform

A high-performance Next.js 16.1 (App Router) Turborepo monorepo for mission-focused organizations, with three apps (apps/admin, apps/donor, apps/missionary) and shared workspace packages (packages/*).

Quickstart

bun run setup
# first run creates .env.local with placeholders
# fill these required values, then re-run `bun run setup`:
# NEXT_PUBLIC_SUPABASE_URL
# NEXT_PUBLIC_SUPABASE_ANON_KEY
bun run dev
bun run verify
# `bun run verify` wraps the bash smoke script; on Windows without shims, use Git Bash / WSL: `bash scripts/verify/index.sh`

Required: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY Optional: All other entries in .env.example (Stripe, demo accounts, Unlayer, etc.)

Cursor Cloud Agent (VM) secrets

For Cursor Cloud Agent runs, set secrets in the Cloud Agent Secrets settings instead of committing values to repo files.

Set these keys in the cloud environment:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY (optional, server-only/admin workflows)

Security rules:

.env.local stays local-only and is already gitignored.
Never expose SUPABASE_SERVICE_ROLE_KEY in browser/client code.
Browser login flows require only NEXT_PUBLIC_SUPABASE_URL + NEXT_PUBLIC_SUPABASE_ANON_KEY.

Windows

Windows PowerShell 5.1:

powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1

PowerShell 7+:

pwsh -File .\scripts\setup.ps1

First run creates .env.local. Fill these required values, then re-run the setup: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY

Skip dependency install if you already ran it:

pwsh -File .\scripts\setup.ps1 -SkipInstall

PowerShell script checks (optional)

Install and run PSScriptAnalyzer locally (not required):

Install-Module PSScriptAnalyzer -Scope CurrentUser
Invoke-ScriptAnalyzer -Path .\scripts\setup.ps1, .\scripts\lib\*.ps1

Architecture & Tech Stack

Framework: Next.js 16.1 (App Router, Turbopack) - Optimized for Performance
UI System: Tailwind CSS 4 + shadcn/ui (Maia Theme) + Base UI
Theme: Light Zinc Aesthetic (Zinc/Zinc), Shadcn/UI Maia Theme
Database: Supabase (PostgreSQL)
Authentication: Supabase Auth (Unified across platforms)
Payments: Stripe (Advanced integration)
State Management: React 19 + TanStack Query v5
Animations: Motion + Tailwind Motion

UX/UI Standards (Shadcn/UI)

The platform follows a standardized Zinc Light theme, optimized for both desktop and mobile viewports with a seamless, responsive transition.

Typography

Primary: Inter (tracking-tight)
Mono:
Headings:

Design Tokens

Padding: Standardized px-4 py-6 sm:px-6 for main content areas.
Borders: Use maia theme tokens, not hard coded zinc. Default to border-border or border-border/60. Keep rounding driven by the Maia radius token --radius.
Motion: Staggered reveals and smooth transitions using MotionPreset.
Responsive: Mobile-first navigation with robust drawers (Sheet) for sidebar access on smaller screens.

Chart Standards

Aesthetic: Data-dense, high-contrast using Maia oklch theme tokens. Use --chart-1 through --chart-5 for series colors.
Bar Charts:
- Radius: Uniform corner radius of [4, 4, 0, 0] on the top segment of stacked bars or all segments of non-stacked bars. Avoid fully rounded domed tops.
- Density: Use maxBarSize={52} for bold, wide bars that scale responsibly.
- Axes: Ensure Y-Axis labels have sufficient width (min 40px) and margin (tickMargin={8}) to prevent numerical cutoff.
- Labels: Use month only for X-Axis time series (e.g., "Nov", "Dec") to maintain high density without clutter.

Multi-Tenant Architecture & Routing

This platform is architected for a multi-tenant environment, allowing a single deployment to serve multiple organizations with isolated data and customized subdomains.

Production Routing Model

In a live production environment, the platform uses dynamic routing based on host headers (subdomains):

Demo Site Accessibility

For this demonstration and development environment, we have implemented aliases to allow easy access to all modules from a single domain:

Mission Control (Admin): Accessible via /admin (mapped to /mc)
Missionary Dashboard: Accessible via /my (mapped to /)
Donor Portal: Accessible via /dashboard (mapped to /donor-dashboard)

Implementation Details

Apps: Route ownership is split across Next.js apps in apps/* (see each app's app/ directory).
Shared auth middleware: Lives in packages/auth/middleware.ts (apps opt in to using it).
Conceptualization: Production routing may use host-based rules; local dev generally runs the apps directly on their dev ports.

Project Modules

Mission Control (Admin Dashboard)

The administrative headquarters for organization leaders. Manage CRM, Contributions, Member Care, and Mobilization with advanced reporting and automation tools.

Route: /mc

Missionary Dashboard

Empowering field missionaries with donor engagement tools, task management, and impact feeds.

My Feed/Ministry Updates: A high-fidelity social engagement platform designed for missionaries to share their journey directly with their support base.
- Functionality: Supports rich text (HTML) storytelling, multi-media carousels for multiple photos, and real-time interaction (Likes, Prayers, Comments).
- Premium Style: Features a high-end "Maia" aesthetic with animated micro-interactions. Clicking a reaction triggers a delightful burst of floating emoji particles (❤️, 🙏, 🔥) and visceral pulsing effects.
- Workflow: Missionaries can save drafts, manage visibility (Public vs Partners Only), and handle follower requests with manual or automated approval levels.
- Media Management: Integrated media toolbar allows for quick image uploads and carousel creation to make updates visually engaging.
Route: /

Donor Portal

A seamless experience for kingdom partners to manage their giving and follow mission progress.

Personalized Impact Feed: A unified, high-fidelity view of updates from all missionaries the donor supports.
The Connection Concept: The platform creates a direct link between generosity and real-world impact.
- Automatic Integration: When a donor makes a contribution to a missionary or clicks "Follow" on their profile, that missionary's feed is automatically integrated into the donor's personalized dashboard.
- Real-Time Updates: Donors receive instant access to stories, prayer requests, and progress reports, allowing them to see exactly how their partnership is making a difference.
- Two-Way Interaction: Donors can respond with reactions and comments, fostering a genuine relationship between the field and the support base.
Route: /donor-portal

Development

This project is optimized for both local development and the Example Cloud (example.com) environment.

AI Agent Guidance System

This repository includes comprehensive AI agent guidance under docs/ai/:

Entry point: AGENTS.md - routing rules for all AI agent work
Stack registry: docs/ai/stack-registry.md - canonical tech stack list
Working set: docs/ai/working-set.md - living task context (keep updated)
Monorepo architecture: docs/ai/monorepo-architecture.md - workspace structure
Rulebooks: docs/ai/rules/* - domain-specific guidelines (frontend, backend, testing, etc.)
Skills: docs/ai/skills/* - reusable workflow patterns

Important: docs/ai/ is the canonical source. The rules/ and skills/ directories at the repository root contain deprecation shims only.

For Cursor-ready runtime skill loading, sync canonical skills into runtime folders after skill updates:

bun run skills:sync

Canonical source: docs/ai/skills/*
Runtime mirrors: .agents/skills/* and .cursor/skills/*

Package Manager

This project uses bun (v1.3+). Do not use npm/yarn/pnpm.

Startup Command: bun run dev

Monorepo Workspace Contract

This repository uses Bun workspaces + Turborepo with this contract:

apps/*      -> deployable applications (admin, donor, missionary)
packages/*  -> shared runtime libraries used by apps
packages/env -> shared environment schema/config package (@asym/env)
tooling/*   -> shared tooling/config packages (eslint, tsconfig, etc.)

Use these placement rules:

Put code in apps/* when it is app-specific routing/UI/behavior.
Put code in packages/* when it is shared across two or more apps.
Use packages/env for shared environment schemas/configuration.
Put code in tooling/* only for build/lint/type/tooling configuration packages.

Workspace conventions:

Every workspace package name must use @asym/<name>.
Internal workspace dependencies must us

Core

Install / Use

README