Concepts

This section explains the core concepts and architectural patterns used throughout LightNap. Each page covers what something is and why it exists; for step-by-step “how do I wire this up” guides, see the Development Guide.

Architecture & Design

Solution & Project Structure

Understand how LightNap is organized: the .NET backend projects, the Angular frontend, and the data flow pattern that connects them. The foundation for everything else.

API Response Model

LightNap’s standardized REST response shape, error handling, and how the Angular client automatically processes responses.

Identity & Sessions

Authentication & Tokens

The JWT-plus-refresh-token model, session lifetime, and how the framework verifies and issues credentials.

Devices

Per-device session tracking — what’s recorded, how stale sessions age out, and how users see and revoke them.

Anonymous Visitor Tracking

Opt-in middleware that mints a per-browser visitor cookie so unauthenticated users have a stable identifier for audit, anonymous UGC, and per-visitor rate limiting that survives NAT and VPN hops.

Data Persistence

JSON Property Storage

[StoredAsJson] persists strongly-typed POCO properties as JSON on entity columns with no per-entity wiring. Behavior is identical across SQLite, SQL Server, and InMemory.

Infrastructure

HTTP Resilience

Wire outbound HttpClients with retry, timeouts, circuit breaker, and a concurrency limiter in one call. Use for every outbound call to a service LightNap doesn’t own.

Operations

Health Check Endpoints

/health/live and /health/ready for container orchestrators and uptime monitors. Readiness covers the database and Redis in distributed mode; liveness is dependency-free.

Background Work

Periodic and Background Tasks

When to use the one-shot LightNap.MaintenanceService model vs an in-process IHostedService with PeriodicTimer. Covers when an external scheduler like Quartz or Hangfire is actually warranted.

Compliance & Audit

Administrative Audit Log

AdminAuditLog entity, IAuditLogger service, and [AuditLog] filter make recording who-did-what on admin endpoints a one-line addition. Retention is configurable; a scheduled maintenance task purges expired entries.

Core Features

Content Management System

LightNap’s built-in CMS — zones, pages, multilingual content, access control, and frontend integration.

Breadcrumb generation from route configuration, including dynamic content from route parameters.

Testing Fundamentals

Testing Fundamentals

Introduction to testing concepts, frameworks, and architecture in LightNap.

Unit Testing Guide

Detailed guide for unit testing Angular components and services with Karma and Jasmine.

E2E Testing Guide

Complete guide for end-to-end testing with Cypress to validate user workflows.

Getting Started

New to LightNap? Start with:

  1. Solution & Project Structure — get oriented with the codebase.
  2. Authentication & Tokens — understand the security model.
  3. API Response Model — learn the API patterns.

Then explore the Development Guide for practical implementation guides.

Table of contents