Technical Architecture & Platform Recommendations

Superseded: This document predates all locked platform decisions and is retained only as a historical record. It must NOT be used as implementation guidance. The decisions below have all been resolved:

• Auth is Clerk (Apple/Google social login — ADR 0003). Not Azure AD B2C / Entra.
• Database is PostgreSQL on Azure DB for PostgreSQL Flexible Server (ADR 0024). Not Azure SQL.
• Compute is Azure Container Apps (containerised Node.js) (ADR 0024). Not Azure Functions / Azure Static Web Apps backend.
• SMS is Twilio (ADR 0013).
• Package manager is pnpm + Turborepo (ADR 0001).

For current guidance see docs/internal/architecture/system-architecture.md, pmo/platform-strategy.md, and the ADRs in docs/internal/adr/.

🚀 Current Epic Priority & Development Path

CRITICAL SEQUENCE (Must Complete In Order):

1. Project Management Setup (Epic #8) - Sprint 000 ✅
2. Technical Architecture & Design (Epic #9) - Sprint 001 🔄
3. UI/UX Design & Portal Mockups (Epic #18) - Sprint 001-002 📋
4. Foundation & Authentication (Epic #1) - Sprint 002-003 📋
5. Calendar System (Epic #6) - Sprint 003-004 📋

Key Business Requirements Addressed:

• ✅ Solution validation and Microsoft alternatives research
• ✅ RBAC deep dive and access control architecture
• ✅ Domain/tenant setup planning
• ✅ Portal mockups and user experience design
• ✅ Faith-friendly technology direction

🎯 Recommended Platform: Azure Static Web Apps + Functions

Why This Stack is Perfect for Your Needs:

1. Cost-Effective: Nearly free for small communities

   • Static Web Apps: Free tier with 100GB bandwidth
   • Azure Functions: 1M requests/month free
   • Azure AD B2C: 50K monthly active users free

2. Religious Organization Benefits:

   • Microsoft Nonprofits Program: Up to $3,500/year Azure credits
   • GitHub for Nonprofits: Free private repositories
   • Office 365 Nonprofit discounts

3. Development-Friendly:

   • Excellent VS Code integration
   • GitHub Copilot fully supported
   • CI/CD built-in with GitHub Actions

4. RBAC Integration:

   • Azure AD B2C for identity management
   • Custom approval workflows
   • Social login (Google, Microsoft, Apple)

🏗️ Phase-by-Phase Development Plan

Phase 1: Project Setup & Architecture (Sprints 000-001)

Focus: Foundation Planning & Technical Design

Priority Order:

1. Project Management Setup (Epic #8) - Complete project structure
2. Technical Architecture (Epic #9) - Solution validation & technology decisions
3. UI/UX Design Planning (Epic #18) - Portal mockups and user experience
4. RBAC Architecture Deep Dive - Access controls and permission system design

Phase 2: Core Infrastructure (Sprints 002-003)

Focus: Authentication & Foundation

Features:

• Repository structure and development environment
• Azure AD B2C identity system with invitation codes
• Database schema for users, roles, events
• Basic authentication with login/logout functionality
• Deployment pipeline with CI/CD setup

Phase 3: Core Calendar (Sprints 003-004)

Focus: MVP Calendar Functionality

Features:

• Event creation with RBAC permissions
• Calendar views (monthly, weekly, daily)
• Event categories and visibility levels
• Basic RSVP functionality

Phase 4: Admin Portal (Sprints 004-005)

Focus: Management & Approval Workflows

Features:

• User approval workflows
• Role management
• Event moderation
• System configuration

Phase 4: Advanced Features (Month 4+)

Focus: Community Enhancement

Features:

• GA vs v.Next environment setup
• Enhanced notifications
• Reporting and analytics
• Mobile-responsive improvements

🛠️ Recommended Tech Stack

Frontend:

• Framework: React with TypeScript
• UI Library: Chakra UI (clean, accessible)
• Calendar: FullCalendar.js
• State Management: Zustand (simpler than Redux)
• Routing: React Router

Backend:

• Platform: Azure Functions (Node.js/TypeScript)
• Database: Azure SQL Database (Basic tier)
• Authentication: Azure AD B2C
• Storage: Azure Blob Storage (for file uploads)

DevOps:

• Hosting: Azure Static Web Apps
• CI/CD: GitHub Actions
• Monitoring: Azure Application Insights
• DNS: Azure DNS or Cloudflare

💡 Immediate Next Steps

1. Apply for Microsoft Nonprofits Program (2-3 weeks processing)
2. Set up Azure subscription with nonprofit benefits
3. Create development environment structure
4. Design database schema with your team
5. Build identity/authentication MVP

Would you like me to start by setting up the repository structure and creating the initial project scaffolding?