Temp_MSSPLASHPage/QWEN.md

QWEN.md - SplashPage Project Context

Project Overview

SplashPage is an ASP.NET Core web application for managing WiFi captive portals and analytics, built on the ABP (ASP.NET Boilerplate) framework. It's designed to work with Cisco Meraki networks to provide WiFi access control, user analytics, and customer engagement features.

Architecture

This is a multi-layered .NET application following Domain-Driven Design (DDD) principles:

Core Components

• SplashPage.Core: Domain entities, enums, and business logic
• SplashPage.Application: Application services, DTOs, and business workflows
• SplashPage.EntityFrameworkCore: Data access layer with Entity Framework Core
• SplashPage.Web.Core: Shared web infrastructure (authentication, controllers)
• SplashPage.Web.Host: Web API host for backend services
• SplashPage.Web.Mvc: MVC web application for frontend
• SplashPage.Migrator: Database migration tool

Key Domain Areas

• Splash: Core WiFi analytics and user connection tracking
• Meraki: Integration with Cisco Meraki API for network data
• Email: Email template management and marketing campaigns with scheduled sending
• Integrations: Third-party service integrations (ZeroBounce email validation, SAML, etc.)
• Perzonalization: Captive portal customization and branding (note: intentional spelling in codebase)
• Reports: Analytics and reporting functionality with real-time metrics
• QRCodes: QR code generation for WiFi access
• Storage: MinIO integration for file storage
• Authorization: Role-based access control and permissions

Database

• Uses Entity Framework Core with MySQL/PostgreSQL
• Multi-tenant architecture enabled
• Connection strings configured in appsettings.json files

Next.js Frontend (SplashPage.Web.Ui)

• Framework: Next.js 14 with App Router
• Styling: Tailwind CSS + shadcn/ui components
• State Management: TanStack Query (React Query)
• API Client: Auto-generated from Swagger with Kubb
• Forms: React Hook Form + Zod validation
• Location: src/SplashPage.Web.Ui/

Key Next.js Routes

• /dashboard - Main admin dashboard
• /dashboard/settings/captive-portal - Portal management and configuration
• /dashboard/settings/captive-portal/[id] - Individual portal configuration page
• /CaptivePortal/Portal/[id] - PUBLIC captive portal display (no auth required)

Captive Portal System

The captive portal system has been migrated from the legacy MVC implementation to Next.js:

Public Portal Routes (No Dashboard Layout):

• /CaptivePortal/Portal/[id] - Production mode (default)

  • Integrates with Cisco Meraki
  • Real form submission and validation
  • Redirects to internet via Meraki grant URL
  • Accepts Meraki query parameters: base_grant_url, gateway_id, client_ip, client_mac, etc.

• /CaptivePortal/Portal/[id]?mode=preview - Preview mode

  • Live preview for configuration testing
  • Simulates validation without real submission
  • Auto-refreshes configuration every 2 seconds
  • Uses fake Meraki parameters in development

Portal Types:

1. Normal Portal: Standard WiFi portal with email, name, birthday fields
2. SAML Portal: Enterprise authentication via SAML/Okta
   • Auto-redirect with configurable delay
   • Manual login button option
   • Customizable branding and messages

Configuration System (Admin Only):

• Located at /dashboard/settings/captive-portal/[id]
• Live preview in iframe
• Offcanvas configuration panel
• Real-time updates in preview mode
• Supports: logos, backgrounds, colors, field validation, terms & conditions, promotional videos

Development Commands

Building the Solution

# Build entire solution
dotnet build SplashPage.sln

# Build specific project
dotnet build src/SplashPage.Web.Mvc/SplashPage.Web.Mvc.csproj

# Build for production
dotnet build SplashPage.sln --configuration Release

Running the Applications

# Run MVC web application (main frontend)
cd src/SplashPage.Web.Mvc
dotnet run

# Run Web API host (backend services)  
cd src/SplashPage.Web.Host
dotnet run

# Run database migrator
cd src/SplashPage.Migrator
dotnet run

# Run benchmarks
cd SplashPage.Benchmarks
dotnet run --configuration Release

Docker Commands

# Build and run with Docker Compose (from docker/mvc directory)
cd docker/mvc
docker-compose up --build

# Build Docker image manually
docker build -t splashpage-mvc .

# Run with Docker (production)
docker run -p 80:80 -e DB_CONNECTION_STRING="your_connection_string" splashpage-mvc

Database Operations

# Run migrations
cd src/SplashPage.Migrator
dotnet run

# Add new migration
cd src/SplashPage.EntityFrameworkCore
dotnet ef migrations add MigrationName --startup-project ../SplashPage.Web.Host

# Update database
dotnet ef database update --startup-project ../SplashPage.Web.Host

Configuration

Environment Variables

• SPLASH_CUSTOMER: Customer identifier for multi-tenant setup
• SPLASH_APP_NAME: Application name identifier
• SPLASH_SKIP_WORKER: Skip background workers during development
• DB_CONNECTION_STRING: Override database connection string
• SPLASH_SECRET: Secret key for authentication

Application URLs

• MVC Web App: https://localhost:44313/ (Development)
• Web API Host: https://localhost:44311/ (Development)

Database Connection

Connection strings are configured in appsettings.json files. The application supports both MySQL and PostgreSQL databases with connection pooling configured.

Key Business Logic

Meraki Integration

• Background workers sync organization and network data from Cisco Meraki
• Real-time scanning data processing for user analytics
• API integration for network device management

WiFi Analytics

• User connection tracking and analytics
• Real-time dashboard with widgets for metrics
• Historical reporting and data visualization
• Customer loyalty analysis and segmentation

Email System

• Template-based email campaigns
• Scheduled email functionality
• Integration with third-party email validation services
• Marketing campaign management

Multi-Tenancy

• Tenant-based data isolation
• Per-tenant configuration and customization
• Captive portal personalization per customer

Important Notes

• The application uses ABP framework conventions for dependency injection and module system
• AutoMapper is used for DTO mappings between layers
• Background workers handle data synchronization tasks (MerakiSyncWorker, EmailProcessorService)
• The system supports multiple database providers through Entity Framework Core
• JWT authentication is implemented for API access
• Multi-language support is available through ABP localization
• OpenTelemetry and Splunk integration for monitoring and observability
• HangFire for background job processing
• Redis caching support available
• SAML authentication support via ITfoxtec.Identity.Saml2
• MinIO object storage integration

Development Workflow

1. Make changes to domain entities in SplashPage.Core
2. Update corresponding DTOs in SplashPage.Application
3. Modify data access in SplashPage.EntityFrameworkCore if needed
4. Add/update controllers in SplashPage.Web.Mvc or SplashPage.Web.Host
5. Run migrations if database schema changes
6. Test both MVC and API endpoints
7. Run benchmarks for performance-critical changes
8. Update configurations in App_Data directories for customer-specific settings

Testing

• The project includes a benchmarking project (SplashPage.Benchmarks)
• No traditional unit test project is present - consider adding xUnit or NUnit tests
• Use the benchmark project to measure performance of critical operations
• Integration testing can be performed using the Web.Host API endpoints

Customer-Specific Configurations

The application supports multiple customer configurations stored in App_Data:

• App_Data/Configuration/captive_portal_config.json - Default configuration
• App_Data/LC/Configuration/ - Little Caesars specific configs
• App_Data/Sultanes/Configuration/ - Sultanes specific configs
• Each customer folder contains both development and production configs

Change Tracking Requirements

IMPORTANT: Whenever you make changes to the codebase, you MUST:

1. Document all changes in the changelog.MD file located in the repository root
2. Include a clear description of what was changed and why
3. Reference the changelog from this CLAUDE.md file to maintain session context
4. Use the changelog to understand previous work when resuming sessions

The changelog serves as a bridge between sessions and provides essential context for ongoing development work. Always check the changelog before starting new work to understand the current state and recent modifications.