Comprehensive Development Plan: CHS Mobile Frontend & Multi-Tenant API Integration

1. Introduction

This document outlines the strategic plan for developing a modern, mobile-first Next.js application (“CHS Mobile”) that integrates seamlessly with the existing C# backend (“ErpCrystal_CHS.Api”). The focus is on implementing a secure, multi-tenant architecture using Firebase Authentication and JWT tokens, while maintaining the stability of the live production application.

2. Current Architecture Overview

• Backend: ASP.NET Core Web API (.NET 9.0) using Dapper. Multi-tenancy is handled via a dbname parameter passed in API routes.
• Frontend (Current): Blazor Server application using MudBlazor.
• Database: Multi-tenant SQL Server setup (System, Common, and Client databases).
• Authentication (Current): Azure AD B2C with API Key validation.

3. Targeted Architecture (SOTA)

3.1 Mobile Frontend (Chsmobileversion)

• Framework: Next.js 14/15 (App Router, Server Components).
• UI/UX: Tailwind CSS + shadcn/ui. Mobile-first design with touch-optimized components.
• PWA: Progressive Web App capabilities for “Add to Home Screen” support on iOS and Android.
• State Management: TanStack Query (fetching/caching) and Zustand (client-side state).
• Authentication: Firebase Client SDK integration.

3.2 Backend Integration (ErpCrystal_CHS.Api)

• JWT Verification Service: A centralized middleware/service to process Firebase JWTs.
• Tenant Context: Automatic extraction of dbname from JWT custom claims.
• Security Logic: Mandatory validation ensuring the requested dbname matches the authenticated user’s assigned database.

---

4. Implementation Strategy

Phase 1: Security & Multi-Tenancy (C# Backend)

Goal: Enable JWT-based multi-tenancy without disrupting the Blazor application.

1. Firebase Integration:
   • Configure Microsoft.AspNetCore.Authentication.JwtBearer to validate Firebase tokens.
   • Setup Authority and TokenValidationParameters for the Firebase Project.
2. Tenant Middleware (FirebaseJwtMiddleware.cs):
   • Intercept all incoming requests.
   • Extract dbname from the claims in the JWT.
   • Store it in HttpContext.Items["ResolvedDbName"].
3. DapperContext Enhancment:
   • Modify DapperContext to use IHttpContextAccessor.
   • Update SetClientConnection(string dbname) to cross-verify the passed dbname with the ResolvedDbName from the JWT.
   • If no dbname is passed (future-proofing), use the ResolvedDbName automatically.

Phase 2: Next.js Mobile Foundation

Goal: Setup the core application shell and auth flow.

1. Project Initialization:
   • npx create-next-app with TypeScript, Tailwind, and App Router.
   • Install shadcn/ui components (Sheet, Nav, BottomTab, etc.).
2. Auth Integration:
   • Implement FirebaseProvider and useAuth hook.
   • Create a clean Login page using shadcn/ui Form and Card.
3. API Client Layer:
   • Build a Fetch wrapper (using Interceptors) that automatically appends the dbname to the URL and injects the Bearer token.
   • Handle 401/403 errors by redirecting to login.

Phase 3: PWA & Mobile UX

Goal: Ensure the app feels like a native mobile application.

1. Installability:
   • Configure manifest.json with appropriate icons and display: standalone.
   • Implement Service Worker for asset caching (offline support).
2. Mobile UX Polish:
   • Implement “Bottom Navigation” for primary app actions.
   • Use “Pull-to-Refresh” and “Swipe Actions” where applicable.
   • Optimize images and fonts for fast mobile loading.

---

5. Technical Decision Matrix

Feature	Recommended	Rationale
Auth Provider	Firebase Auth	Scalable, handles custom claims for dbname, and hosts the frontend.
Data Fetching	TanStack Query	Superior caching and synchronization for mobile networks.
Database Routing	JWT Claims	Authoritative and secure; prevents users from accessing other DBs via URL spoofing.
PWA Config	Native Manifest	Better control over iOS/Android specific meta tags.

6. Risk Mitigation & Compliance

• Stable Production: All C# changes will be “add-only” or “fallback-safe” to ensure the existing Blazor app never breaks.
• Cross-Tenant Security: The backend must enforce that the JWT dbname claim matches the request. If a user tries to access a different dbname, the API will return 401 even if the API Key is valid.
• SSL/TLS: All communications will be over HTTPS, especially since tokens are passed in headers.

7. Immediate Next Steps

1. Verify Firebase Project settings and custom claims structure.
2. Draft the FirebaseJwtMiddleware in a separate branch of ErpCrystal_CHS.Api.
3. Initialize the Next.js repository in the Chsmobileversion folder.
4. Conduct a POC call from Next.js to the C# API with a valid token.