paxalia-dashboard

PyPI Version Python Django License

A privacy-first, self-hosted analytics, observability, security, and administration platform for Django, from Paxalia.

paxalia-dashboard brings product analytics, runtime/server visibility, security monitoring, persistent structured logging, release context, reporting, data utilities, and a full Django-native administrative workspace into one package that runs inside your own Django application.

There is no required third-party analytics SaaS, tracking pixel, hosted collector, or cloud dashboard.

Optional integrations such as billing models, Celery, Slack, Discord, email delivery, or webhooks are enabled only when your host project configures them.

Table of Contents

Paxalia Dashboard v4.0.0 — Final Security & Usage Overview

Paxalia Dashboard v4.0.0 is a complete Django-native operational workspace: analytics, runtime observability, persistent logging, security monitoring, administration, data portability, reporting, integrations, localization, and a dedicated administrator authentication boundary all live inside the Django application that owns the data.

The v4 administrator security model is intentionally layered. The dashboard does not rely on a single password, a hidden URL, or a browser fingerprint as its only protection.

Paxalia Administrator Access

1. Password
      ↓
2. Mandatory 2FA
      ↓
3. Authorized Device
      ↓
4. Authentication Rate Limits
      ↓
5. CSRF Protection
      ↓
6. Isolated Administrator Authentication
      ↓
7. Secret Dashboard Path
      ↓
Protected Paxalia Dashboard

The first three layers are the required authentication chain. The remaining layers are defense-in-depth controls around that chain:

Password → TOTP / recovery → WebAuthn device
             │
             ├── login / 2FA / device rate limits
             ├── Django CSRF enforcement
             ├── dedicated Paxalia SessionStore + cookie
             └── deployment-specific private dashboard path

The default administrator mode is isolated:

Host Website Authentication
        │
        └── host session / host cookies
                 │
                 │   completely separate
                 ▼
Paxalia Administrator Authentication
        │
        ├── password
        ├── Paxalia TOTP
        ├── authorized WebAuthn credential
        └── paxalia_admin_session

The two systems can use the same Django user model and the same Django session backend without sharing the same session state. This keeps the package independently usable while preventing ordinary host login, host 2FA, host session rotation, or host logout behavior from becoming the Paxalia administrator session.

The complete v4 presentation layer also includes twelve built-in themes built on shared design tokens, responsive desktop, tablet, and mobile layouts, RTL support, bundled chart/map assets, and reusable component styling.

Why paxalia-dashboard

paxalia-dashboard is a Django-native operational intelligence and administration layer for real applications.

It started from the practical need to understand what an application is doing, but a real product eventually needs much more than page-view analytics. It needs a way to observe behavior, investigate failures, understand infrastructure, review security, administer application data, move structured data between environments, and keep important operational context close to the application itself.

Paxalia Dashboard brings those concerns together inside the Django project that owns the data.

The platform combines:

  • product and traffic analytics
  • behavioral analytics
  • bot and crawler classification
  • real user monitoring
  • JavaScript error visibility
  • server/runtime monitoring
  • slow-query and queue visibility
  • uptime checks and incident history
  • release and deployment context
  • security monitoring
  • persistent structured logging
  • reporting and protected sharing
  • API access and scoped keys
  • backup utilities
  • historical data import
  • multi-site analytics
  • compliance controls
  • a generic Django-native Admin
  • localization-aware administration
  • model-aware .paxalia package import/export
  • operational diagnostics and maintenance commands

The central design goal is:

Keep operational data close to the application that produced it, make the data inspectable, and let Django remain the source of truth.

That means Paxalia Dashboard is deliberately broad, but it is still a Django application package. It is not an alternative to Django and it does not attempt to replace Django's core responsibilities.

Your Django application continues to own:

  • models and the ORM
  • authentication
  • permissions
  • URL routing
  • forms and business rules
  • migrations
  • database infrastructure
  • deployment
  • the operating system
  • the reverse proxy
  • physical backup/disaster-recovery systems

Paxalia adds the operational, analytical, security, administrative, and data-workflow layer around that application.

Comparison at a glance

The following comparison is intentionally broad. Paxalia Dashboard is not just an analytics counter; its scope reaches from product measurement and browser telemetry through server operations, security, persistent logging, administration, localization, and logical data portability.

This is a directional capability comparison rather than a procurement benchmark. Third-party products vary by product, edition, plan, integration, and deployment. N/A means the capability is outside the primary purpose of that category. Varies means support depends substantially on the specific product or deployment.

Area Capability Google Analytics Typical lightweight Django analytics package paxalia-dashboard
Foundation Self-hosted application ❌ ✅ ✅
Foundation First-party storage in host infrastructure ❌ ✅ ✅
Foundation Django-native integration ❌ ✅ ✅
Foundation Required hosted analytics collector ✅ Usually no ❌
Foundation No mandatory analytics SaaS dependency ❌ Usually yes ✅
Foundation Bundled chart assets ❌ Varies ✅
Foundation Bundled map assets ❌ Rare ✅
Foundation No public CDN required for core dashboard assets ❌ Varies ✅
Foundation Single configurable package surface ❌ Varies ✅
Foundation Host-project configuration namespace ❌ Varies ✅
Foundation Optional external integrations Varies Varies ✅
Analytics Page views ✅ ✅ ✅
Analytics Sessions ✅ ✅ ✅
Analytics Session duration ✅ Varies ✅
Analytics Bounce-related metrics ✅ Varies ✅
Analytics Pages per session ✅ Varies ✅
Analytics One-click date presets ✅ Varies ✅
Analytics Arbitrary date ranges ✅ Varies ✅
Analytics Previous-period comparison ✅ Rare ✅
Analytics Searchable page tables ✅ Varies ✅
Analytics Paginated page tables ✅ Varies ✅
Analytics Traffic-source analysis ✅ Varies ✅
Analytics Referrer analysis ✅ Varies ✅
Analytics Browser breakdown ✅ Varies ✅
Analytics Operating-system breakdown ✅ Varies ✅
Analytics Device breakdown ✅ Varies ✅
Analytics API traffic separation Varies Rare ✅
Analytics API endpoint analytics Varies Rare ✅
Analytics Status-code distribution Varies Rare ✅
Analytics Real-time visitor monitoring ✅ Rare ✅
Analytics Recent activity feed Varies Rare ✅
Analytics Search-query parameter analysis Varies Rare ✅
Geography Offline GeoIP database support ❌ Rare ✅
Geography Country analysis ✅ Rare ✅
Geography City analysis ✅ Rare ✅
Geography Offline world-map presentation ❌ Rare ✅
Geography Country-to-city drill-down Varies Rare ✅
Behavioral Custom event tracking ✅ Varies ✅
Behavioral Event categories/actions/labels ✅ Varies ✅
Behavioral Event numeric values ✅ Rare ✅
Behavioral Goal definitions ✅ Rare ✅
Behavioral Funnel definitions ✅ Rare ✅
Behavioral Funnel drop-off analysis ✅ Rare ✅
Behavioral Reusable behavioral segments ✅ Rare ✅
Behavioral Campaign/UTM analysis ✅ Varies ✅
Behavioral Campaign-source analysis ✅ Varies ✅
Behavioral Campaign-medium analysis ✅ Varies ✅
Behavioral Campaign-name analysis ✅ Varies ✅
Behavioral Cohort analysis ✅ Rare ✅
Behavioral Retention analysis ✅ Rare ✅
Behavioral Chart annotations Varies Rare ✅
Behavioral Deployment-linked annotations ❌ Rare ✅
Web quality Broken-link / 404 analysis Varies Rare ✅
RUM Core Web Vitals ✅ Rare ✅
RUM LCP collection ✅ Rare ✅
RUM CLS collection ✅ Rare ✅
RUM INP collection ✅ Rare ✅
RUM 75th-percentile presentation ✅ Rare ✅
RUM Good/needs-improvement/poor breakdown ✅ Rare ✅
RUM Browser JavaScript error capture ✅ Rare ✅
RUM window.onerror capture Varies Rare ✅
RUM Unhandled rejection capture Varies Rare ✅
RUM Browser error deduplication Varies Rare ✅
RUM Bounded browser error ingestion Varies Rare ✅
Uptime Scheduled HTTP checks Varies Rare ✅
Uptime GET monitoring Varies Rare ✅
Uptime HEAD monitoring Varies Rare ✅
Uptime POST monitoring Varies Rare ✅
Uptime Expected status-code validation Varies Rare ✅
Uptime Configurable timeout Varies Rare ✅
Uptime Per-monitor intervals Varies Rare ✅
Uptime Status history Varies Rare ✅
Uptime Transition-based incidents Varies Rare ✅
Uptime Recovery detection Varies Rare ✅
Uptime Uptime percentage Varies Rare ✅
Uptime Uptime alert integration Varies Rare ✅
Bot intelligence Bot-path classification Varies Rare ✅
Bot intelligence Search-engine crawler classification Varies Rare ✅
Bot intelligence AI crawler classification Varies Rare ✅
Bot intelligence Social-preview classification Varies Rare ✅
Bot intelligence SEO-tool classification Varies Rare ✅
Bot intelligence Generic bot classification Varies Rare ✅
Bot intelligence Malicious/scanner classification Varies Rare ✅
Bot intelligence Dedicated Bot Traffic dashboard Varies Rare ✅
Bot intelligence Historical bot-category backfill Varies Rare ✅
Server CPU monitoring ❌ ❌ ✅
Server Per-core CPU history ❌ ❌ ✅
Server Load-average monitoring ❌ ❌ ✅
Server Memory monitoring ❌ ❌ ✅
Server Swap monitoring ❌ ❌ ✅
Server Disk usage ❌ ❌ ✅
Server Disk I/O history ❌ ❌ ✅
Server Network-interface statistics ❌ ❌ ✅
Server Network traffic history ❌ ❌ ✅
Server System-service visibility ❌ ❌ ✅
Server Process monitoring ❌ ❌ ✅
Server Slow-query capture ❌ ❌ ✅
Server Configurable slow-query threshold ❌ ❌ ✅
Server Celery queue visibility ❌ ❌ ✅
Server Deployment recording ❌ ❌ ✅
Server Deployment-to-chart correlation ❌ ❌ ✅
Security Security Center ❌ Rare ✅
Security Login activity visibility Varies Rare ✅
Security Failed-login monitoring Varies Rare ✅
Security Active-session visibility Varies Rare ✅
Security Session-revocation visibility Varies Rare ✅
Security IP blocklist controls ❌ Rare ✅
Security Optional blocking middleware ❌ Rare ✅
Security CSP violation reporting ❌ Rare ✅
Security Security scorecard ❌ Rare ✅
Security Mandatory administrator TOTP 2FA ❌ Rare ✅
Security Backup-download re-authentication ❌ Rare ✅
Security Failed-login threshold detection Varies Rare ✅
Security Security email alerts Varies Rare ✅
Security Security webhook alerts Varies Rare ✅
Security In-dashboard alert history Varies Rare ✅
Security Security audit events ❌ Rare ✅
Logging Persistent structured application logging ❌ Rare ✅
Logging Standard Python logging capture ❌ Rare ✅
Logging Django logger capture ❌ Rare ✅
Logging Direct paxalia.log() API ❌ ❌ ✅
Logging Request lifecycle logging ❌ ❌ ✅
Logging Request ID context ❌ Rare ✅
Logging Correlation ID context ❌ Rare ✅
Logging Trace ID context ❌ Rare ✅
Logging Session context ❌ Rare ✅
Logging User context ❌ Rare ✅
Logging Site context ❌ Rare ✅
Logging Traffic context ❌ Rare ✅
Logging Browser-error integration ❌ Rare ✅
Logging Exception-type storage ❌ Rare ✅
Logging Stack-trace storage ❌ Rare ✅
Logging Stable event fingerprints ❌ Rare ✅
Logging Event grouping ❌ Rare ✅
Logging Occurrence counting ❌ Rare ✅
Logging Suppression counting ❌ Rare ✅
Logging Representative samples ❌ Rare ✅
Logging Grouping windows ❌ Rare ✅
Logging Handler-topology deduplication ❌ Rare ✅
Logging Configurable sensitive-key redaction ❌ Rare ✅
Logging Bounded log-message sizes ❌ Rare ✅
Logging Bounded stack sizes ❌ Rare ✅
Logging Bounded structured metadata ❌ Rare ✅
Logging Bounded browser event rate ❌ Rare ✅
Logging Category-specific retention ❌ Rare ✅
Logging Request-less/background logging ❌ Rare ✅
Logging Detailed incident investigation ❌ Rare ✅
Logging Related-event discovery ❌ Rare ✅
Logging Sanitized “Copy for AI” context ❌ Rare ✅
Administration Generic Django-native Admin workspace ❌ Varies ✅
Administration Django Admin registry as source of truth ❌ Rare ✅
Administration Application grouping ❌ Rare ✅
Administration Dynamic model discovery ❌ Varies ✅
Administration Capability discovery ❌ Rare ✅
Administration Searchable model catalog ❌ Rare ✅
Administration Application collapse/expand ❌ Rare ✅
Administration Metadata-aware model search ❌ Rare ✅
Administration list_display compatibility ❌ Varies ✅
Administration Search compatibility ❌ Varies ✅
Administration Filter compatibility ❌ Varies ✅
Administration Ordering compatibility ❌ Varies ✅
Administration Pagination ❌ Varies ✅
Administration Date hierarchy support ❌ Rare ✅
Administration list_editable compatibility ❌ Rare ✅
Administration Query-state preservation ❌ Rare ✅
Administration Django ModelForm integration ❌ Varies ✅
Administration Fieldsets ❌ Varies ✅
Administration Read-only fields ❌ Varies ✅
Administration Object-level permission hooks ❌ Rare ✅
Administration Safe create/read/update/delete ❌ Varies ✅
Administration Deletion preview ❌ Rare ✅
Administration Protected/dependent deletion handling ❌ Rare ✅
Administration Safe bulk deletion ❌ Rare ✅
Administration Django custom actions ❌ Rare ✅
Administration ForeignKey inspection ❌ Rare ✅
Administration OneToOne inspection ❌ Rare ✅
Administration ManyToMany inspection ❌ Rare ✅
Administration Reverse-relation inspection ❌ Rare ✅
Administration Self-reference handling ❌ Rare ✅
Administration TabularInline support where representable ❌ Rare ✅
Administration StackedInline support where representable ❌ Rare ✅
Administration Model statistics ❌ Rare ✅
Administration Choice distributions ❌ Rare ✅
Administration Created/updated counts where detectable ❌ Rare ✅
Administration History view ❌ Rare ✅
Administration Audit context ❌ Rare ✅
Administration Sensitive-field masking ❌ Rare ✅
Administration Django Admin fallback for exotic behavior ❌ N/A ✅
Localization Configured-language discovery ❌ Rare ✅
Localization Translation-system discovery ❌ Rare ✅
Localization django-parler-style support ❌ Rare ✅
Localization Translation completeness ❌ Rare ✅
Localization Missing-translation inspection ❌ Rare ✅
Localization Language-aware editing ❌ Rare ✅
Localization RTL-compatible presentation ❌ Rare ✅
Localization Translation-aware exports ❌ Rare ✅
Localization Translation-aware imports ❌ Rare ✅
Packages Logical .paxalia package format ❌ Rare ✅
Packages Versioned package metadata ❌ Rare ✅
Packages ZIP package container ❌ Rare ✅
Packages Manifest validation ❌ Rare ✅
Packages SHA-256 integrity validation ❌ Rare ✅
Packages Duplicate ZIP-member protection ❌ Rare ✅
Packages Archive path-traversal protection ❌ Rare ✅
Packages Size/count safety limits ❌ Rare ✅
Packages Selected-model export ❌ Rare ✅
Packages Filtered-model export ❌ Rare ✅
Packages Multi-model export ❌ Rare ✅
Packages Identity-aware export/import ❌ Rare ✅
Packages Configurable identity fields ❌ Rare ✅
Packages ForeignKey preservation ❌ Rare ✅
Packages OneToOne preservation ❌ Rare ✅
Packages ManyToMany preservation ❌ Rare ✅
Packages Self-reference preservation ❌ Rare ✅
Packages Translation preservation ❌ Rare ✅
Packages UUID serialization ❌ Rare ✅
Packages Decimal/date/time serialization ❌ Rare ✅
Packages File-field logical-path serialization ❌ Rare ✅
Packages Lazy-translation serialization ❌ Rare ✅
Packages Configurable conflict strategies ❌ Rare ✅
Packages Import preview ❌ Rare ✅
Packages Dry-run import ❌ Rare ✅
Packages Atomic import ❌ Rare ✅
Packages Partial-success import ❌ Rare ✅
Packages Structured failure reporting ❌ Rare ✅
Packages Failed-subset retry packages ❌ Rare ✅
Packages Protected-model encryption requirements ❌ Rare ✅
Packages Authenticated package encryption ❌ Rare ✅
Packages Wrong-password handling ❌ Rare ✅
Packages Tamper detection ❌ Rare ✅
Packages Permission-aware package operations ❌ Rare ✅
Packages Package operation auditability ❌ Rare ✅
Packages CLI package validation ❌ Rare ✅
Packages CLI package inspection ❌ Rare ✅
Operations Backup path configuration ❌ ❌ ✅
Operations Backup storage management ❌ ❌ ✅
Operations Scheduled backup support ❌ ❌ ✅
Operations Backup retention ❌ ❌ ✅
Operations Background backup creation ❌ ❌ ✅
Operations Chunked large-file download ❌ ❌ ✅
Operations Chunked upload workflow ❌ ❌ ✅
Operations Historical GA aggregate CSV import Varies Rare ✅
Operations Historical Plausible aggregate CSV import Varies Rare ✅
Operations Per-data-type retention Varies Rare ✅
Operations Visitor-deletion tooling Varies Rare ✅
Operations Scheduled email reports Varies Rare ✅
Operations PDF reports Varies Rare ✅
Operations Protected dashboard sharing Varies Rare ✅
Operations Scoped API keys ✅ Rare ✅
Operations API documentation surface ✅ Rare ✅
Operations Slack command surface Varies Rare ✅
Operations Discord command surface Varies Rare ✅
Operations Multi-site analytics Varies Rare ✅
Operations Dependency-closure inspection ❌ ❌ ✅
Operations Release-artifact context ❌ Rare ✅
Operations In-dashboard notifications Varies Rare ✅
Operations Email alert destinations Varies Rare ✅
Operations Webhook alert destinations Varies Rare ✅
Diagnostics Dashboard-wide diagnostics ❌ Rare ✅
Diagnostics Admin-specific diagnostics ❌ Rare ✅
Diagnostics Logging-specific diagnostics ❌ Rare ✅
Diagnostics Package inspection CLI ❌ Rare ✅
Diagnostics Package validation CLI ❌ Rare ✅
Diagnostics Focused Admin test suite ❌ Rare ✅
Diagnostics Logging test suite ❌ Rare ✅
Diagnostics Scheduled maintenance commands ❌ Rare ✅
Presentation Internationalized UI Varies Rare ✅
Presentation RTL dashboard support Varies Rare ✅
Presentation Responsive desktop/tablet/mobile UI Varies Varies ✅
Presentation Theme system Varies Rare ✅
Presentation Multiple built-in themes Varies Rare ✅
Presentation Shared design-token styling ❌ Rare ✅
Presentation Offline chart/map assets ❌ Rare ✅

The important difference is not simply the number of checkmarks. It is the co-location of these capabilities: the same Django application can own the analytics data, runtime context, logs, security signals, administrative workflows, and logical package operations without creating another independent operational data plane.

The real value: features you notice later

Not every feature has the same visibility.

Some capabilities are immediately attractive because their value is visible at a glance:

  • analytics charts
  • real-time visitors
  • geography
  • RUM
  • security scorecards
  • server dashboards
  • elegant reports

Other capabilities are quieter. They are often the features a team does not think about while building a prototype, but they can become unusually important once the application is a real product with real data, real users, real incidents, and real operational history.

A useful way to understand Paxalia is:

WHAT ATTRACTS YOU FIRST
        ↓
analytics
RUM
security
server visibility
reports
        ↓
WHAT BECOMES IMPORTANT LATER
        ↓
persistent logging
request correlation
generic administration
permissions
safe CRUD
relationships
localization
package export/import
identity resolution
translation preservation
failure reporting
retry workflows
retention
diagnostics
auditability

The production gap

During early development, a team can often work with:

database
+
Django Admin
+
a few logs
+
a few analytics charts

As the product grows, the operational questions become more demanding.

You start needing to know:

What failed?
Where?
For which request?
For which user/session?
Was it one failure or thousands?
Is there a common fingerprint?
Did it begin after a deployment?
Is the problem in the browser, application, API, or server?
What related events happened around it?

You also start needing to answer administrative questions:

Which models exist?
Which applications own them?
Which permissions apply?
Which fields are sensitive?
Which records can this administrator change?
Which relationships exist?
Which translations are missing?
Which actions are available?
How can a subset of application data be moved safely?

And eventually data portability becomes practical:

Can I export selected models?
Can I preserve relationships?
Can I preserve translations?
Can I resolve identities without blindly restoring primary keys?
Can I preview the result before changing the database?
Can I dry-run it?
Can I choose update/skip behavior?
Can I perform an atomic import?
Can I isolate independent failures?
Can I retry only the failed subset?
Can protected data require encryption?
Can I validate the package before importing it?

Those are not always "shining" features.

They are the kind of features that become valuable because the application exists in the first place.

Why the package is intentionally large

Paxalia Dashboard is large because it covers a wide operational surface around Django, not because it tries to replace Django.

The package is best understood as a set of connected layers:

                 Django application
                        │
       ┌────────────────┼────────────────┐
       │                │                │
       ▼                ▼                ▼
   Analytics         Security         Application
       │                │              operations
       │                │                │
       ├───────┬────────┴───────┬────────┤
       │       │                │        │
       ▼       ▼                ▼        ▼
      RUM    Logging          Admin   Packages
       │       │                │        │
       └───────┴────────────────┴────────┘
                        │
                        ▼
              one Django-native view

The point is not that every team needs every feature every day.

The point is that a production product eventually crosses multiple concerns, and Paxalia provides a coherent place to handle those concerns without forcing each one into a completely separate system.

A deliberate balance

Paxalia Dashboard therefore has two kinds of value:

VISIBLE VALUE
    dashboards
    analytics
    RUM
    security
    reports

QUIET VALUE
    logs
    context
    admin
    permissions
    portability
    package integrity
    localization
    diagnostics
    retention
    audit

The first group may get someone interested.

The second group can be what makes the package difficult to replace once it becomes part of the application's operating workflow.

That balance is intentional.

What Paxalia Dashboard is — and is not

Paxalia Dashboard is a large Django application package, but it does not attempt to become a second Django.

It does not replace:

  • Django's ORM
  • Django models
  • Django authentication
  • Django permissions
  • Django URL routing
  • Django forms
  • Django migrations
  • Django Admin
  • your database
  • your reverse proxy
  • your operating system
  • your deployment system
  • your infrastructure
  • your physical disaster-recovery strategy

Instead, it integrates with Django's existing architecture.

The administrative data flow is deliberately:

Django Admin registry
        ↓
Paxalia Admin registry/adapter
        ↓
permissions
        ↓
query + services + forms
        ↓
Paxalia Admin views
        ↓
Paxalia UI

The generic package workflow is similarly additive:

registered Django models
        ↓
permission-aware selection
        ↓
logical serialization
        ↓
identity / relationships / translations
        ↓
integrity + security
        ↓
.paxalia package

And the logging workflow is another layer around normal application execution:

Python / Django logging
        +
paxalia.log()
        ↓
normalization
        ↓
request/runtime context
        ↓
redaction
        ↓
fingerprint/grouping
        ↓
persistent observability

Django remains the authority.

Paxalia supplies additional operational intelligence around it.

Paxalia Dashboard and the wider Paxalia ecosystem

paxalia-dashboard is the open-source Django-focused project in the broader Paxalia product ecosystem.

The main Paxalia application is a much larger systemizing app built around Workspaces and connected systems for organizing work, time, goals, information, visual thinking, collaboration, portability, synchronization, and offline continuity.

The relationship is best understood as:

Paxalia
    ↓
systemize
connect
organize
operate
    ↓
Paxalia Dashboard
    ↓
help Django applications
observe
understand
protect
administer
and move their application data

The dashboard is useful independently. It does not require the main Paxalia application to run.

At the same time, it shares the broader Paxalia philosophy of building systems that become more useful when the parts connect.

Paxalia is still evolving, and the dashboard is intended as a strong foundation rather than a claim that the ecosystem has reached its final form. Future releases can add deeper integrations, more automation, more intelligent operational tooling, and other capabilities as the product and its community grow.

Features

Paxalia is intentionally a platform rather than a single dashboard widget. Features are modular: a host project can use the analytics layer, observability layer, security layer, Admin layer, package workflows, or operational utilities according to its needs.

Analytics

  • Page Views & Sessions — page visits, sessions, duration, bounce-related metrics, and pages-per-session reporting.
  • Traffic Sources — referrers, browsers, operating systems, devices, and source breakdowns.
  • Date Range Analysis — reusable presets plus explicit start/end ranges.
  • Period Comparison — compare the selected period with its corresponding previous period.
  • Interactive Tables — searchable, paginated operational tables with CSV/JSON export where supported.
  • API Traffic Analytics — separate API activity from normal page traffic using configurable rules.
  • Real-Time Monitoring — live visitor and recent-request views with configurable refresh intervals.
  • Geography — offline GeoIP-backed country and city analysis with a bundled map asset workflow.

Behavioral analytics

  • Custom Events — track product interactions such as clicks, form submissions, video engagement, and downloads.
  • Goals — define conversion targets and measure completion behavior.
  • Funnels — inspect multi-step conversion paths and drop-off.
  • Segments — build reusable behavioral audience definitions.
  • Campaign / UTM Analytics — compare campaign source, medium, and campaign performance.
  • Cohorts — analyze return/retention behavior across visitor cohorts.
  • Annotations — connect important operational dates such as deployments, incidents, or launches to analytics charts.
  • Broken Links — identify paths returning 404 responses and inspect their referring context.

Runtime observability

  • Real User Monitoring — LCP, CLS, INP and field-performance breakdowns.
  • JavaScript Error Tracking — browser exceptions and unhandled rejections with bounded ingestion.
  • Uptime Monitoring — scheduled HTTP checks, status history, and transition-based incidents.
  • Server Monitoring — CPU, memory, disk, network, services, and processes.
  • Slow Query Monitoring — opt-in database query timing.
  • Celery Monitoring — worker/task visibility when the host Celery application is configured.
  • Deployment Tracking — release/deployment records connected to chart annotations.
  • Persistent Logs — application and request observability in the same operational dashboard.

Security

  • Mandatory Administrator Authentication — privileged dashboard access requires password authentication, confirmed TOTP/recovery verification, and an authorized WebAuthn device credential.
  • Administrator Authentication Isolation — the default mode stores the final Paxalia administrator session in a dedicated Django SessionStore and a separate paxalia_admin_session cookie scoped to the dashboard path.
  • Authentication Rate Limiting — login, 2FA, and device ceremonies have independent configurable attempt/window limits; failed-login thresholds also feed Security Center alerting.
  • CSRF Protection — authentication and state-changing browser operations are designed to remain behind Django's CSRF middleware; the bundled WebAuthn JSON helper sends the current CSRF token with POST requests.
  • Secret Dashboard Path — the full administrator surface can be mounted below a deployment-specific private path; production configuration requires a high-entropy URL-safe segment.
  • Security Center — authentication activity, active sessions, IP blocklists, security events, and posture.
  • Security Scorecard — security configuration findings in one operational view.
  • CSP Violation Reporting — application-level visibility into browser policy violations.
  • Mandatory Administrator 2FA — every privileged Paxalia Dashboard administrator must complete the configured TOTP second-factor enrollment and verification before administrative access is established.
  • Backup Re-authentication — recent authentication can be required before sensitive backup downloads.
  • Sensitive Data Redaction — common credential and secret fields are sanitized before persistent presentation/storage where the package policy applies.
  • Auditability — privileged dashboard/admin/package operations can be connected to the existing audit/security architecture.

Administration and data portability

  • Generic Paxalia Admin — a Django-native model administration layer.
  • Model Search and Discovery — searchable application/model catalog with collapse/expand behavior.
  • Django Permission Reuse — registered ModelAdmin permission hooks remain authoritative.
  • CRUD and Actions — normal administrative workflows without host-model hard-coding.
  • Relationships and Inlines — inspect and manage supported Django relationship structures.
  • Localization Workspace — discover and edit supported translation systems using configured project languages.
  • Package Center — model-aware .paxalia import/export.
  • Package Validation — structural and integrity validation before package mutation.
  • Encrypted Packages — authenticated encryption for protected/sensitive package flows.
  • Retry Packages — retry failed subsets without reconstructing them manually.

Operations and utilities

  • Backup Management — configurable paths, storage, retention, scheduled backups, and chunked transfer.
  • Historical Data Import — GA/Plausible aggregate CSV import without vendor OAuth credentials.
  • Reporting — scheduled email/PDF reports where configured.
  • Protected Sharing — read-only sharing for selected dashboard views.
  • Scoped API Keys — explicit read/ingestion scopes instead of an all-purpose secret.
  • Dependency Health — inspect runtime dependency state and progressively compare installed versions with available releases.
  • Notifications & Alerts — in-dashboard history plus optional email/webhook delivery.
  • Multi-Site Analytics — multiple configured domains represented through Site records.
  • Release Center — release artifacts and deployment context.

Localization and presentation

  • Internationalization — bundled dashboard translations for five languages in the package distribution.
  • RTL — Arabic support and direction-aware dashboard behavior.
  • Themes — twelve built-in themes using shared design tokens.
  • Responsive UI — desktop, tablet, and mobile layouts.
  • Offline Assets — charts, maps, and fonts do not require a public CDN at runtime.

Tech Stack

The package is intentionally substantial because it covers several application-lifecycle concerns around Django. The dependency footprint remains focused on Django and the subsystems this dashboard actually provides; optional integrations are not required unless the host project enables them.

Component Technology
Backend Django 5.0+ / Django 6.0 compatible
Python Python 3.10+
Database Any Django-supported database; PostgreSQL is a supported production target
Charts Chart.js, bundled
World Map Datamaps + D3.js + TopoJSON, bundled
GeoIP MaxMind GeoLite2-City + geoip2
User-Agent Parsing user-agents
Country Codes pycountry
Server Metrics psutil
Package Encryption cryptography
TOTP / Administrator 2FA django-otp
WebAuthn / Device Auth webauthn
Administrative Integration django.contrib.admin / ModelAdmin
Authentication boundaries Host Django authentication + mandatory 2FA + authorized WebAuthn device

The current package metadata declares Python >=3.10, Django >=5.0, and includes Django 5.0 and Django 6.0 classifiers.

Runtime dependency set

The current package declares the following runtime dependencies. This is the package dependency set rather than a list of optional dependencies from a particular host application:

Package Declared requirement Used for
Django >=5.0 Core framework, ORM, sessions, authentication, forms, middleware, migrations
user-agents >=2.2.0 Browser, operating-system, and device classification
geoip2 >=4.8.0 Offline GeoIP lookup support
psutil >=5.9.0 Server CPU, memory, disk, network, process, and service metrics
pycountry >=22.3.5 Country-code and country-name support
django-honeypot >=1.2.1 Honeypot integration used by hardened host deployments
cryptography >=46.0.0 Authenticated package/data encryption primitives
django-otp >=1.7.0,<2.0 Mandatory administrator TOTP authentication
qrcode >=8.0,<9.0 QR presentation for TOTP enrollment
webauthn >=3.0.0,<4.0 Layer 3 WebAuthn registration and authentication

A host project can have additional dependencies such as its own Redis, Celery, Sentry, REST framework, or authentication packages. Those belong to the host application and are not silently counted as Paxalia Dashboard runtime requirements. fileciteturn29file2L1-L34

Installation

1. Install the package

pip install paxalia-dashboard

For local development:

pip install -e .

2. Add paxalia to INSTALLED_APPS

INSTALLED_APPS = [
    # ...
    "paxalia",
]

3. Include the dashboard URLs

The dashboard is designed to live under a private path chosen by the host project.

A minimal installation can mount:

from django.urls import include, path

urlpatterns = [
    # ...
    path("insights/", include("paxalia.urls")),
]

In a hardened production installation, many projects also mount Django Admin itself under a separate secret path.

For example:

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("insights/", include("paxalia.urls")),
    path("private-admin/", admin.site.urls),
]

The exact dashboard/admin paths are host-project decisions.

4. Add the analytics middleware

MIDDLEWARE = [
    # Django/security/session middleware ...
    "paxalia.middleware.AnalyticsMiddleware",
]

AnalyticsMiddleware resolves sites, classifies requests, records page-view/session information, and feeds the analytics subsystem.

4a. Mount the dashboard under a deployment-specific secret path

The administrator surface should live under a private, non-predictable route chosen by the host project.

For development, a simple route such as /insights/ is acceptable. Production deployments should use a dedicated 32–128 character URL-safe random segment:

export ENVIRONMENT=production
export DASHBOARD_URL="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')"

Expose that value through the host settings:

import os

DASHBOARD_URL = os.environ["DASHBOARD_URL"]

PAXALIA_DASHBOARD = {
    # ...
    "DASHBOARD_URL": DASHBOARD_URL,
}

Then mount Paxalia below that path:

from django.conf import settings
from django.urls import include, path

urlpatterns = [
    path(
        settings.DASHBOARD_URL.lstrip("/"),
        include("paxalia.urls"),
    ),
]

Every administrator authentication route then lives below the same private mount:

<secret-dashboard-path>/auth/login/
<secret-dashboard-path>/auth/2fa/setup/
<secret-dashboard-path>/auth/2fa/verify/
<secret-dashboard-path>/auth/device/
<secret-dashboard-path>/security/
<secret-dashboard-path>/admin/...

The secret path is defense in depth, not authentication. The password, 2FA, device, rate-limit, CSRF, and session boundaries remain mandatory.

4b. Enable the isolated Paxalia administrator session

In the default mode, place the dedicated Paxalia session middleware immediately after Django's normal SessionMiddleware, and place the isolated administrator authentication middleware after Django's AuthenticationMiddleware:

MIDDLEWARE = [
    # ...
    "django.contrib.sessions.middleware.SessionMiddleware",

    "paxalia.auth_middleware.PaxaliaIsolatedSessionMiddleware",

    # ...
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",

    "paxalia.auth_middleware.PaxaliaIsolatedAdminAuthenticationMiddleware",

    # ...
    "paxalia.middleware.SecurityBlockMiddleware",
    "paxalia.logging.middleware.PaxaliaLoggingMiddleware",
    "paxalia.middleware.SlowQueryMiddleware",
    "paxalia.middleware.AnalyticsMiddleware",
]

The default isolated mode is:

PAXALIA_DASHBOARD = {
    # ...
    "AUTH_USE_HOST_LOGIN": False,
    "AUTH_ISOLATED_SESSION_COOKIE_NAME": "paxalia_admin_session",
    "AUTH_ISOLATED_SESSION_COOKIE_SAMESITE": "Lax",
    "ADMIN_SESSION_MAX_AGE_SECONDS": 8 * 60 * 60,
}

The resulting administrator cookie is scoped to the dashboard path. Paxalia logout deletes the isolated administrator session without flushing the host website session.

4c. Optional host-authentication compatibility mode

Projects that deliberately want Paxalia to participate in an existing host login/2FA flow can opt in:

PAXALIA_DASHBOARD = {
    # ...
    "AUTH_USE_HOST_LOGIN": True,
    "AUTH_LOGIN_URL": None,
    "AUTH_HOST_2FA_URL_NAMES": ("core:login-2fa",),
    "AUTH_HOST_2FA_INTENT_TTL_SECONDS": 600,
}

When this compatibility mode is enabled, the host project's successful second-factor route can hand the administrator back to the protected Paxalia destination through the signed, short-lived handoff implemented by PaxaliaAdminHost2FARedirectMiddleware.

The middleware does not grant dashboard access by itself and does not change ordinary host login redirects when there is no active Paxalia administrator intent.

5. Run migrations

python manage.py migrate paxalia

The platform includes a deterministic migration chain for the analytics, security, compliance, operations, reporting, notification, and observability models.

6. Enable strict CSP correctly

The packaged dashboard is designed for CSP-safe script delivery.

A host project using a strict CSP should expose the existing Paxalia analytics configuration context processor and the CSP nonce context processor:

TEMPLATES = [
    {
        "OPTIONS": {
            "context_processors": [
                # ...
                "paxalia.context_processors.analytics_config",
                "csp.context_processors.nonce",
            ],
        },
    },
]

When using django-csp, configure its middleware and nonce policy according to the version installed by the host project.

Example:

from csp.constants import NONCE

CONTENT_SECURITY_POLICY = {
    "DIRECTIVES": {
        "default-src": ("'self'",),
        "script-src": (
            "'self'",
            NONCE,
            "'strict-dynamic'",
        ),
    }
}

Do not weaken your CSP merely to make Paxalia run.

7. Compile translations

python manage.py compilemessages -l es -l ar -l zh-hans -l pt-br

Use the actual language codes present in the host deployment.

8. Install the GeoIP database

The GeoIP database is intentionally not bundled into the repository because of its size.

Download GeoLite2-City from MaxMind and point GEOIP_PATH at the .mmdb file:

PAXALIA_DASHBOARD = {
    "GEOIP_PATH": "/srv/paxalia/GeoLite2-City.mmdb",
}

The geography page can otherwise present an empty/limited state rather than fabricating location data.

9. Start the server

python manage.py runserver localhost:8000

Open the dashboard at the path you configured, for example:

http://localhost:8000/<secret-dashboard-path>/

10. Create or authorize a dashboard administrator

By default, the package recognizes Django users that are is_staff or is_superuser as administrators. Projects with a custom administrator role can supply SECURITY_ADMIN_USER_CHECK.

For a fresh local project, Django's standard command is sufficient:

python manage.py createsuperuser

Then use the Paxalia login route beneath the secret dashboard mount:

http://localhost:8000/<secret-dashboard-path>/auth/login/

The final administrator session is created only after the full required authentication chain completes:

password
  ↓
confirmed TOTP / recovery code
  ↓
authorized WebAuthn device
  ↓
Paxalia administrator session

http://localhost:8000/<secret-dashboard-path>/

Configuration

All package behavior is configured through the host project's PAXALIA_DASHBOARD dictionary.

The package merges the supplied configuration with safe built-in defaults.

A representative configuration surface is:

PAXALIA_DASHBOARD = {
    # ── Navigation ───────────────────────────────────────────────
    "SIDEBAR_SECTIONS": [
        "overview",
        "pages",
        "api",
        "traffic",
        "realtime",
        "bots",
        "geography",
        "events",
        "billing",
        "releases",
        "backups",
        "security",
        "sites",
        "broken_links",
        "goals",
        "funnels",
        "segments",
        "campaigns",
        "annotations",
        "cohorts",
        "api_keys",
        "reports",
        "share_links",
        "notifications",
        "rum",
        "uptime",
        "compliance",
        "data_import",
        "settings",
    ],

    # ── Analytics / GeoIP ───────────────────────────────────────
    "API_PATH_PREFIX": "/api/",
    "GEOIP_PATH": None,
    "DEFAULT_ANONYMIZE_IP": False,
    "DEFAULT_IGNORED_PREFIXES": ["/admin/", "/static/", "/media/"],
    "DEFAULT_IGNORED_EXTENSIONS": [
        ".css",
        ".js",
        ".png",
        ".jpg",
        ".svg",
        ".ico",
        ".woff2",
    ],
    "DEFAULT_REALTIME_REFRESH": 30,
    "DEFAULT_SEARCH_QUERY_PARAMS": ["q", "search", "query"],

    # ── Billing integration ─────────────────────────────────────
    "BILLING_INVOICE_MODEL": "billing.BillingInvoice",
    "BILLING_USER_PLAN_MODEL": "billing.UserBilling",
    "BILLING_DONATION_MODEL": "billing.Donation",

    # ── Uploads / imports ───────────────────────────────────────
    "UPLOADS_INCOMING_ROOT": None,
    "UPLOAD_CHUNK_SIZE_MB": 5,
    "UPLOAD_MAX_FILE_SIZE_MB": 2048,
    "DATA_IMPORT_MAX_FILE_SIZE_MB": 100,
    "UPLOAD_SESSION_TTL_HOURS": 24,

    # ── Proxy / IP trust ────────────────────────────────────────
    "TRUST_X_FORWARDED_FOR": False,
    "TRUSTED_PROXY_COUNT": 1,

    # ── Security Center ─────────────────────────────────────────
    "SECURITY_TRACK_ONLY_STAFF": True,
    "SECURITY_LOG_RETENTION_DAYS": 180,
    "SECURITY_FAILED_LOGIN_THRESHOLD": 5,
    "SECURITY_FAILED_LOGIN_WINDOW_MINUTES": 15,
    "SECURITY_ALERT_EMAILS": [],
    "SECURITY_ALERT_WEBHOOK_URL": None,
    "BACKUP_REAUTH_MINUTES": 15,

    # ── Server / operations ─────────────────────────────────────
    "SERVER_METRIC_RETENTION_DAYS": 7,
    "SLOW_QUERY_THRESHOLD_MS": 100,
    "CELERY_APP_PATH": None,

    # ── Compliance ──────────────────────────────────────────────
    "CONSENT_MODE_ENABLED": False,
    "CONSENT_COOKIE_NAME": "analytics_consent",
    "CONSENT_COOKIE_GRANTED_VALUE": "granted",
    "DATA_RETENTION_DAYS": {},

    # ── Integrations ───────────────────────────────────────────
    "SLACK_SIGNING_SECRET": None,
    "DISCORD_PUBLIC_KEY": None,

    # ── Multi-site ──────────────────────────────────────────────
    "AUTO_CREATE_SITES": False,

    # ── Anomaly detection ───────────────────────────────────────
    "ANOMALY_ALERT_THRESHOLD_PERCENT": 30,

    # ── Persistent Logging / Observability ──────────────────────
    "LOGGING_ENABLED": True,
    "LOG_CAPTURE_STANDARD_LOGGING": True,
    "LOG_MIN_LEVEL": "INFO",
    "LOG_REQUEST_SUCCESSES": False,
    "LOG_REQUEST_ID_RESPONSE_HEADER": "X-Paxalia-Request-ID",
    "LOG_MAX_MESSAGE_LENGTH": 4000,
    "LOG_MAX_STACK_LENGTH": 12000,
    "LOG_MAX_METADATA_BYTES": 16384,
    "LOG_DEDUPE_WINDOW_SECONDS": 60,
    "LOG_MAX_SAMPLES_PER_GROUP": 5,
    "LOG_BROWSER_MAX_EVENTS_PER_PAGE": 50,
    "LOG_BROWSER_MAX_REQUESTS_PER_MINUTE": 120,
    "LOG_BROWSER_MAX_PAYLOAD_BYTES": 32768,
    "LOG_BROWSER_CAPTURE_CONSOLE": False,
    "LOG_BROWSER_CAPTURE_RESOURCE_ERRORS": True,
    "LOG_RELEASE": None,
    "LOG_SENSITIVE_KEYS": [],
    "LOG_RETENTION_DAYS": {
        "system": 30,
        "request": 30,
        "browser": 30,
        "application": 30,
        "login": 180,
        "security": 180,
        "group": 90,
    },
    "SECURITY_STORE_FAILED_USERNAME": True,
    "SECURITY_ADMIN_USER_CHECK": None,
    "APPLICATION_LOGS": [],

    # ── Paxalia Admin ───────────────────────────────────────────
    "ADMIN_ENABLED": True,
    "ADMIN_MODEL_ALLOWLIST": [],
    "ADMIN_MODEL_DENYLIST": [],
    "ADMIN_MODELS": {},
    "ADMIN_LIST_PER_PAGE": 50,
    "ADMIN_MAX_RELATION_ITEMS": 10,
    "ADMIN_MAX_BULK_OPERATIONS": 500,
    "ADMIN_SENSITIVE_FIELDS": [
        "password",
        "password_hash",
        "token",
        "access_token",
        "refresh_token",
        "secret",
        "client_secret",
        "signing_secret",
        "api_key",
        "apikey",
        "private_key",
        "session_key",
        "csrf_token",
        "authorization",
        "cookie",
        "credential",
        "credentials",
        "secret_key",
        "encryption_key",
    ],
    "ADMIN_DJANGO_FALLBACK_ENABLED": True,
    "ADMIN_LIST_EDITABLE_ENABLED": True,
    "ADMIN_MAX_DELETE_PREVIEW": 100,
    "ADMIN_OBJECT_HISTORY_PER_PAGE": 30,
    "ADMIN_PROTECTED_NO_STORE": True,

    # ── Paxalia Packages ────────────────────────────────────────
    "PACKAGE_MAX_FILE_SIZE_MB": 100,
    "PACKAGE_MAX_OBJECTS": 10000,
    "PACKAGE_MAX_RELATIONS": 50000,
    "PACKAGE_REQUIRE_ENCRYPTION_FOR_PROTECTED": True,
    "PACKAGE_ALLOWED_CONFLICTS": ["update", "skip"],
}

The current package configuration surface include the Admin and logging sections above.

Mandatory administrator security configuration

The administrator security controls are policy parameters rather than feature switches. The three authentication layers cannot be disabled through normal dashboard configuration.

A complete security-focused configuration can be expressed as:

PAXALIA_DASHBOARD = {
    # ── Administrator security policy ─────────────────────────────
    "ADMIN_MAX_DEVICES": 5,
    "ADMIN_SESSION_MAX_AGE_SECONDS": 8 * 60 * 60,

    # Layer 1 — password/login rate limiting
    "SECURITY_LOGIN_RATE_LIMIT_ATTEMPTS": 8,
    "SECURITY_LOGIN_RATE_LIMIT_WINDOW_SECONDS": 15 * 60,

    # Layer 2 — TOTP rate limiting
    "SECURITY_2FA_RATE_LIMIT_ATTEMPTS": 5,
    "SECURITY_2FA_RATE_LIMIT_WINDOW_SECONDS": 5 * 60,

    # Layer 3 — WebAuthn/device rate limiting
    "SECURITY_DEVICE_RATE_LIMIT_ATTEMPTS": 5,
    "SECURITY_DEVICE_RATE_LIMIT_WINDOW_SECONDS": 5 * 60,

    # Layer 3 — WebAuthn ceremony
    "WEBAUTHN_CHALLENGE_TTL_SECONDS": 120,
    "WEBAUTHN_RP_NAME": "Paxalia Dashboard",
    "WEBAUTHN_RP_ID": None,
    "WEBAUTHN_ORIGIN": None,

    # Separate Paxalia administrator session
    "AUTH_USE_HOST_LOGIN": False,
    "AUTH_ISOLATED_SESSION_COOKIE_NAME": "paxalia_admin_session",
    "AUTH_ISOLATED_SESSION_COOKIE_SAMESITE": "Lax",
    "AUTH_ISOLATED_SESSION_COOKIE_DOMAIN": None,

    # Public authentication surfaces
    "AUTH_SIGNUP_ENABLED": True,
    "AUTH_PASSWORD_RESET_ENABLED": True,
    "AUTH_PASSWORD_CHANGE_ENABLED": True,

    # Recovery
    "SECURITY_RECOVERY_CODE_COUNT": 10,

    # Private destination / presentation
    "AUTH_BRAND_NAME": "Paxalia",
    "AUTH_HOME_URL": "/",
    "AUTH_ADMIN_HOME_URL": None,
    "AUTH_SUPPORT_URL": None,
}

Important policy details:

  • AUTH_USE_HOST_LOGIN=False is the default and keeps Paxalia's administrator authentication separate from the host website authentication.
  • AUTH_ISOLATED_SESSION_COOKIE_NAME defaults to paxalia_admin_session.
  • The isolated cookie path follows the configured dashboard path.
  • ADMIN_MAX_DEVICES limits the number of active administrator device credentials.
  • Login, TOTP, and WebAuthn/device ceremonies each have independent rate limits.
  • WebAuthn challenges are short-lived and single-use.
  • WEBAUTHN_RP_ID and WEBAUTHN_ORIGIN should be set explicitly in production when TLS terminates at a reverse proxy or when a stable deployed origin is known.
  • SECURITY_RECOVERY_CODE_COUNT controls the number of recovery codes generated for the administrator recovery path.
  • These settings tune policy values; they do not remove the mandatory authentication layers.

Secret-path deployment policy

For production deployments, DASHBOARD_URL is validated as a 32–128 character URL-safe random path segment. Predictable paths such as /admin/, /dashboard/, /insights/, /paxalia/, or /login/ must not be used as the production secret mount.

A typical deployment shape is:

Public application
    ├── normal website login
    ├── normal website sessions
    └── public ingestion endpoints

Private Paxalia mount
    ├── auth/login/
    ├── auth/2fa/
    ├── auth/device/
    ├── security/
    ├── admin/
    ├── logs/
    ├── packages/
    └── dashboard pages

The same private mount is used for the administrator UI and its authentication lifecycle, so the dashboard's privileged surfaces are not scattered across conventional public routes.

CSRF requirements

Keep Django CSRF middleware enabled:

MIDDLEWARE = [
    # ...
    "django.middleware.csrf.CsrfViewMiddleware",
    # ...
]

Do not add a blanket csrf_exempt around Paxalia authentication or package-management views. The bundled browser authentication helper sends the current CSRF token for JSON POST requests, including WebAuthn ceremonies.

fileciteturn28file0L1-L20

Configuration groups

Navigation

SIDEBAR_SECTIONS controls the navigation sections displayed and their order.

A section can still require a corresponding integration or capability before it is useful. Optional areas should not be enabled just for decoration.

Analytics

API_PATH_PREFIX determines what traffic is treated as API traffic. DEFAULT_ANONYMIZE_IP controls the default IP storage behavior. Ignored prefixes and extensions help avoid polluting analytics with static and administrative requests.

Uploads

UPLOADS_INCOMING_ROOT controls staging. Chunk size, total upload size, and session TTL are bounded so upload handling does not become unbounded temporary storage.

Proxy and IP trust

TRUST_X_FORWARDED_FOR must only be enabled behind a reverse proxy you control.

Do not blindly trust arbitrary client-supplied X-Forwarded-For values.

TRUSTED_PROXY_COUNT describes how many trusted proxy hops should be considered when resolving the client IP.

Security

Security Center settings control staff-only tracking, log retention, failed-login thresholds, alert destinations, and backup download re-authentication.

Logging

The logging settings control capture level, request logging, response request-ID headers, message/stack/metadata bounds, deduplication, browser ingestion limits, retention, and redaction configuration.

Admin

The Admin settings control which registered models are exposed, page sizes, relationship display limits, bulk operation limits, sensitive field policies, fallback behavior, list-editable support, deletion preview limits, history pagination, and no-store handling.

Packages

Package limits protect import/export operations from unexpected scale.

PACKAGE_ALLOWED_CONFLICTS controls which conflict strategies may be used. The package UI and engine enforce these settings rather than trusting arbitrary user-provided values.

Model-specific Admin configuration

ADMIN_MODELS provides optional per-model configuration without making Paxalia depend on a host application's model names.

For example:

PAXALIA_DASHBOARD = {
    "ADMIN_MODELS": {
        "content.article": {
            "identity_fields": ["slug"],
            "sensitive_fields": ["private_token"],
        },
    },
}

This is a configuration extension point.

It does not replace Django registration and should not be used to build hard-coded model-specific business logic into Paxalia.

Host Django settings

The host project remains responsible for:

  • INSTALLED_APPS
  • MIDDLEWARE
  • TEMPLATES
  • database configuration
  • cache configuration
  • email delivery
  • sessions and cookies
  • CSRF settings
  • CORS
  • CSP
  • ASGI/WSGI deployment
  • reverse proxy configuration
  • authentication and identity policy

Middleware Integration

Paxalia provides multiple middleware capabilities.

AnalyticsMiddleware

Required for page-view/session collection:

MIDDLEWARE = [
    # ...
    "paxalia.middleware.AnalyticsMiddleware",
]

Responsibilities include:

  • request classification
  • site resolution
  • page-view creation
  • session handling
  • bot/API classification
  • configured ignore rules
  • analytics aggregation feed

SecurityBlockMiddleware

Optional.

Place it before analytics when you want blocked IPs rejected before analytics records are created:

MIDDLEWARE = [
    # ...
    "paxalia.middleware.SecurityBlockMiddleware",
    "paxalia.middleware.AnalyticsMiddleware",
]

SlowQueryMiddleware

Optional.

MIDDLEWARE = [
    # ...
    "paxalia.middleware.SlowQueryMiddleware",
    "paxalia.middleware.AnalyticsMiddleware",
]

It observes Django database query execution and persists queries that reach the configured threshold.

PaxaliaLoggingMiddleware

Optional.

Place it after the host's session/authentication context when you want Paxalia request IDs, request lifecycle events, response status, and duration context:

MIDDLEWARE = [
    # security/session/auth middleware ...
    "paxalia.logging.middleware.PaxaliaLoggingMiddleware",
    "paxalia.middleware.AnalyticsMiddleware",
]

It is intentionally separate from AnalyticsMiddleware.

The two systems answer different questions:

Analytics
    "What happened to the site's traffic?"

Logging / Observability
    "What happened inside the application while that request was executing?"

Recommended ordering

A common production arrangement is:

MIDDLEWARE = [
    # Django / proxy / security / session / authentication ...

    "paxalia.middleware.SecurityBlockMiddleware",
    "paxalia.logging.middleware.PaxaliaLoggingMiddleware",
    "paxalia.middleware.SlowQueryMiddleware",
    "paxalia.middleware.AnalyticsMiddleware",
]

Exact ordering depends on the host application's middleware stack.

Dashboard Pages

Page URL Purpose
Overview / Core traffic summary, trends, top pages, API activity, and comparison
Pages /pages/ Tracked paths, search, pagination, and page-level drill-down
Page Detail /pages/…/ Detailed historical traffic for an individual path
API /api/ API traffic, endpoint activity, and status-code distribution
Traffic /traffic/ Referrers, browsers, operating systems, and device types
Geography /geography/ Offline world map, countries, and cities
Events /events/ Custom events and event breakdowns
Real-time /realtime/ Current live visitor activity
RUM /rum/ Core Web Vitals and browser errors
Uptime /uptime/ Monitors, uptime history, and incidents
Compliance /compliance/ Consent, retention, and visitor-deletion controls
Data Import /import/ Historical aggregate CSV import
Billing /billing/ Optional billing and revenue integration
Server Overview /server/overview/ CPU, memory, disk, network and host health
Server CPU /server/cpu/ CPU detail and history
Server Memory /server/memory/ RAM and swap
Server Disk /server/disk/ Storage and I/O
Server Network /server/network/ Interface traffic and network statistics
Server Services /server/services/ Running system services
Server Processes /server/processes/ Active process information
Server Slow Queries /server/slow-queries/ Queries crossing the configured latency threshold
Server Queues /server/queues/ Celery state where configured
Server Deployments /server/deployments/ Deployment history and chart context
Security /security/ Application security posture and security events
Admin Overview /admin-overview/ High-level user/content/login activity
Bot Traffic /bots/ Bot volume, categories, paths and geography
Backups /backups/ Backup configuration, creation and downloads
Reports /reports/ Scheduled reporting
Share Links /share-links/ Protected read-only sharing
Notifications /notifications/ Dashboard notifications and alerts
Sites /sites/ Multi-site configuration
Dependencies /dependencies/ Runtime dependency health
Settings /settings/ Dashboard preferences and operational settings
Logs /logs/ Canonical persistent Paxalia Logs dashboard
Application Logs /application-logs/ Application-oriented log view
Login Activity /login-activity/ Authentication/login observability
Log Detail /logs/<id>/ Full structured event investigation
Paxalia Admin /admin/.../ Generic Django-native Admin under the dashboard's protected mount

Exact route prefixes depend on the host project's dashboard mounting configuration.

Administrator authentication routes

The routes below are relative to the dashboard's configured mount:

Route Purpose
/auth/login/ Layer 1 administrator password login
/auth/logout/ End the isolated Paxalia administrator session
/auth/signup/ Public Paxalia-branded signup surface when enabled
/auth/password-reset/ Start password recovery
/auth/password-reset/<uidb64>/<token>/ Password-reset confirmation
/auth/password-change/ Change the current password
/auth/2fa/setup/ Enroll the mandatory Paxalia TOTP authenticator
/auth/2fa/verify/ Verify the Layer 2 TOTP/recovery step
/auth/2fa/reset/ Reset the Paxalia 2FA state through the supported recovery flow
/auth/recovery/regenerate/ Regenerate administrator recovery codes
/auth/device/ Start Layer 3 authorized-device authentication
/auth/device/options/ Select an available authorized-device option
/auth/device/verify/ Complete WebAuthn authentication
/auth/device/register/ Start authorized-device registration
/auth/device/register/verify/ Complete WebAuthn device registration
/auth/session-expired/ Show the expired administrator-session state
/auth/access-denied/ Show the protected access-denied state

These routes are intentionally part of the private dashboard mount in the normal deployment model.

Cross-dashboard behavior

Where supported:

  • date ranges are shared through the standard dashboard filtering language
  • common presets include Today, Yesterday, Last 7 days, Last 30 days, and current month
  • charts provide previous-period comparison
  • tables provide export actions
  • responsive layouts adapt to desktop, tablet, and mobile
  • Arabic layouts operate in RTL

Custom Event Tracking

Track product interactions without adding another analytics provider.

Quick start

Use the bundled event script:

<script src="{% static 'paxalia/scripts/analytics-events.js' %}"></script>

The host project should ensure the script receives the appropriate CSP nonce when a strict CSP requires one.

Data attributes

<button
        data-analytics-category="download"
        data-analytics-action="click"
        data-analytics-label="windows">
    Download for Windows
</button>

Forms can use the same mechanism:

<form
        data-analytics-category="form"
        data-analytics-action="submit"
        data-analytics-label="contact-form">
    ...
</form>

JavaScript API

window.opAnalytics(
    "video",
    "play",
    "intro-tutorial",
    1
);

Event fields

Field Required Description
category Yes Broad grouping such as button, video, or form
action Yes Event action such as click, play, or submit
label No Additional event context
value No Optional numeric value
path No Page path, normally derived from the browser location

Real User Monitoring

RUM is integrated into the existing browser event system.

Web Vitals

Paxalia collects:

  • LCP — Largest Contentful Paint
  • CLS — Cumulative Layout Shift
  • INP — Interaction to Next Paint

The dashboard presents field-data summaries and percentile-oriented reporting instead of pretending these measurements are laboratory benchmarks.

JavaScript errors

Browser-side errors are collected through:

  • window.onerror
  • unhandledrejection

The client limits event volume and deduplicates repeated failures to avoid runaway error loops.

Captured data can include:

  • message
  • filename
  • line/column
  • stack
  • page context

Storage

Web Vitals reuse the existing event model.

JavaScript errors use the dedicated JSError model because useful browser failure diagnostics need more room and structure than the generic event label field.

RUM caveats

RUM represents real visitor environments.

It varies with:

  • device
  • network
  • browser
  • workload
  • application architecture

INP is captured using the package's supported browser-side measurement approach and should be interpreted as field telemetry rather than a promise of full laboratory conformance for every application architecture.

Uptime Monitoring

Uptime monitoring performs scheduled HTTP checks against configured endpoints.

Monitor configuration

A monitor can specify:

  • name
  • URL
  • HTTP method
  • expected status code
  • timeout
  • check interval

Scheduling

Run the check command from cron or Celery beat.

Example:

* * * * * cd /path/to/project && python manage.py check_uptime >> /var/log/paxalia-uptime.log 2>&1

Incident model

Incidents are transition-based.

A continuously failing service is represented as one incident rather than one incident row per check.

A recovery closes the incident.

Alerts

Uptime transitions reuse the package's alert/notification infrastructure and can optionally produce dashboard notifications plus configured email/webhook delivery.

A period with zero checks is represented as an empty/unknown state rather than falsely reported as 0% or 100%.

Compliance

Paxalia's compliance tooling is application-level and intentionally separate from a legal compliance certification.

Consent mode

Consent mode is disabled by default.

To require consent:

PAXALIA_DASHBOARD = {
    "CONSENT_MODE_ENABLED": True,
    "CONSENT_COOKIE_NAME": "analytics_consent",
    "CONSENT_COOKIE_GRANTED_VALUE": "granted",
}

The host project's consent banner/CMP remains responsible for obtaining consent and setting the cookie.

The server-side gate is authoritative.

Without the required consent:

  • page-view tracking is skipped
  • anonymous session state is not created
  • event endpoints can return a skipped response
  • client tracking becomes a no-op

Data retention

Retention is configurable by data type:

PAXALIA_DASHBOARD = {
    "DATA_RETENTION_DAYS": {
        "pageview": 400,
        "analytics_event": 400,
        "js_error": 90,
        "uptime_check": 90,
        "slow_query": 30,
    },
}

Nothing is pruned unless you explicitly configure a retention policy.

Forget this visitor

The compliance surface can delete stored analytics rows associated with a visitor identifier.

Because different observability models contain different identifiers, not every subsystem can necessarily be matched by every identifier type.

The current implementation documents those limitations rather than pretending a deletion request reached data that cannot be identified through the same field.

Privacy principle

Deletion is recorded as an audit action without reintroducing the exact raw identifier into the audit trail.

Data Import

Historical aggregate imports are supported for Google Analytics and Plausible CSV exports.

Why CSV

Paxalia deliberately avoids requiring:

  • Google OAuth credentials
  • vendor API clients
  • vendor-specific long-lived secrets

A CSV export is already an artifact under the site's control.

Supported scope

The historical importer is designed for daily aggregate statistics.

It does not attempt to reconstruct individual page-view rows from aggregate exports.

Common metric mapping

External column Paxalia field
views / pageviews total_views
visitors / users closest supported unique-visitor field
sessions total_sessions
bounce rate derived bounce count where both rate and sessions are available

Metrics that cannot be derived safely remain empty/zero rather than being fabricated.

Existing dates

Existing daily rows are skipped by default so a historical import does not silently overwrite live analytics.

An explicit overwrite mode is available for deployments that intentionally want replacement behavior.

Slack/Discord App

Paxalia supports both outgoing alert delivery and signed incoming command surfaces.

Slack

Configure:

PAXALIA_DASHBOARD = {
    "SLACK_SIGNING_SECRET": "your-secret",
}

The Slack endpoint verifies request signatures with HMAC-SHA256.

Discord

Configure:

PAXALIA_DASHBOARD = {
    "DISCORD_PUBLIC_KEY": "your-public-key",
}

Discord signature verification requires a compatible Ed25519 implementation; PyNaCl can be installed when that feature is required.

Scope

The command surface reuses the same high-level analytics snapshot logic used by reporting and sharing.

Typical periods include:

  • today
  • yesterday
  • this week
  • this month

The command response is deliberately plain text so it behaves consistently across supported chat platforms.

Admin Overview

The existing Admin Overview gives administrators a high-level summary of application activity.

It includes:

  • total users
  • recent registrations
  • active-user-oriented metrics
  • content totals
  • content creation history
  • login activity
  • recent administrative/security context where available

This is intentionally different from Paxalia Admin.

Admin Overview
    = operational summary

Paxalia Admin
    = generic model administration

Server Monitoring

Server monitoring reads metrics directly from the host using psutil.

No external monitoring agent is required.

Available views

  • Overview
  • CPU
  • Memory
  • Disk
  • Network
  • Services
  • Processes
  • Slow Queries
  • Queues
  • Deployments

History snapshots

Historical server charts are backed by persisted ServerMetricSnapshot data.

Schedule:

* * * * * cd /path/to/project && python manage.py record_server_metrics >> /var/log/paxalia-server.log 2>&1

The command also prunes data older than SERVER_METRIC_RETENTION_DAYS.

If no snapshots have been collected, the dashboard displays an empty state instead of synthetic values.

Slow queries

Enable:

MIDDLEWARE = [
    # ...
    "paxalia.middleware.SlowQueryMiddleware",
]

Then configure:

PAXALIA_DASHBOARD = {
    "SLOW_QUERY_THRESHOLD_MS": 100,
}

The middleware uses Django's query execution instrumentation and guards its own persistence from recursive capture.

Celery queues

Configure:

PAXALIA_DASHBOARD = {
    "CELERY_APP_PATH": "myproject.celery.app",
}

Celery remains optional.

If it is not installed or not configured, the queue view returns an empty state rather than failing the dashboard.

Deployments

After deployment:

python manage.py record_deployment \
    --version "$(git rev-parse --short HEAD)" \
    --notes "Deploy from main"

A deployment record is stored and linked to a chart annotation.

Bot Traffic

Paxalia separates crawler/scanner traffic from normal analytics.

Path classification

You can configure known bot/scanner paths such as:

/robots.txt
/.env
/wp-admin/
/xmlrpc.php

A path match can classify a request as malicious/bot traffic.

User-Agent classification

The classifier also recognizes categories such as:

  • search engines
  • AI crawlers
  • social preview bots
  • SEO tools
  • generic bot-like clients
  • malicious/scanner traffic

Important limitation

User-Agent strings are claims made by the client.

Paxalia does not perform live crawler-IP verification.

A client that spoofs a legitimate crawler User-Agent can therefore be misclassified when visiting an ordinary page.

Attack-probe paths can still override those claims because a request for a known malicious path is meaningful evidence of scanner activity regardless of the reported User-Agent.

Backfilling existing traffic

When bot classification rules change, existing PageView rows are not silently rewritten.

Run:

python manage.py backfill_pageview_bot_category --dry-run

Then run the command without --dry-run when the results are understood.

Importing large path lists

python manage.py import_bot_paths /path/to/bot_paths.txt

Use --replace when you intentionally want to replace the configured list rather than merge it.

Backup Management

Backup Management is a physical/system backup facility and should not be confused with .paxalia logical packages.

Features

  • configurable source paths
  • configurable storage directory
  • scheduled backups
  • retention settings
  • on-demand creation
  • background processing
  • chunked large-file download
  • archive status
  • restore/delete workflows where supported
  • recent-authentication checks for sensitive downloads

Re-authentication

The host can require recent staff authentication before a backup download:

PAXALIA_DASHBOARD = {
    "BACKUP_REAUTH_MINUTES": 15,
}

This check is applied to every download request.

Scheduled backups

Example:

0 2 * * * cd /path/to/project && python manage.py create_backup >> /var/log/paxalia-backup.log 2>&1

Backup policy remains a deployment responsibility.

Internationalization

The current distribution includes translations for:

Language Code RTL
English en No
Spanish es No
Arabic ar Yes
Simplified Chinese zh-hans No
Brazilian Portuguese pt-br No

Arabic uses RTL layout direction.

The language system is based on Django's standard internationalization workflow.

Adding another language

A normal workflow is:

mkdir -p paxalia/locale/<code>/LC_MESSAGES

Then add/translate the corresponding .po file and compile:

python manage.py compilemessages -l <code>

The generic dashboard uses Django translation tags rather than hard-coded per-language template branches.

Admin localization

Paxalia Admin's model localization workspace is different from the dashboard UI translation catalog.

For model translation data:

  • supported languages are discovered from Django configuration
  • translation systems are discovered from model metadata
  • supported translation APIs are reused
  • missing translations are identified
  • translations can be edited where the model exposes a supported editing surface
  • package import/export can carry multilingual translation data

There is no six-language hard-coded Admin branch.

Themes

The current dashboard ships with twelve themes.

Theme Slug Character
Dark Gold dark Deep charcoal and warm gold
Skybound Silk default Soft light presentation
Golden Dusk golden Cream and gold
Azure Drift azure Cool blue
Sunlit Meadow sunlit Bright green
Indigo Spectrum indigo Violet night
Arctic Horizon arctic Icy blue
Ocean Breeze ocean Teal and navy
Twilight Reverie twilight Deep violet
Velvet Noir velvet Crimson / dark
Citrine Prestige citrine Gold-forward
Onyx Pearl onyx Minimal dark / silver

Theme contract

Themes are applied using the existing:

data-analytics-theme="..."

contract and the shared --analytics-* token vocabulary.

Persistence

The selected theme is persisted in browser storage.

Custom themes

Add a new theme selector to the existing theme stylesheet:

[data-analytics-theme="your-slug"] {
    --analytics-bg: # . . .;
    --analytics-surface: # . . .;
    --analytics-border: # . . .;
    --analytics-text: # . . .;
    --analytics-text-dim: # . . .;
    --analytics-gold: # . . .;
    --analytics-gold-dim: rgba(...);
    --analytics-gold-hover: # . . .;
    --analytics-compare: # . . .;
}

Then expose it through the settings theme list.

Do not introduce a second theme system.

Exporting Data

Paxalia provides normal table exports throughout the dashboard.

CSV

CSV is suitable for:

  • Excel
  • Google Sheets
  • scripts
  • operational review

JSON

JSON is intended for:

  • scripts
  • integrations
  • data inspection
  • programmatic use

Export context

Dashboard exports respect relevant filters such as:

  • selected date range
  • page/path search
  • country selection
  • current table/query context

Exports must not be interpreted as unrestricted database dumps.

Spreadsheet safety

Administrative/logging exports are expected to use safe serialization for values that might otherwise be interpreted as spreadsheet formulas.

Billing Integration

Billing is intentionally model-configurable.

Paxalia does not own or replace your billing system.

Configuration

PAXALIA_DASHBOARD = {
    "BILLING_INVOICE_MODEL": "billing.BillingInvoice",
    "BILLING_USER_PLAN_MODEL": "billing.UserBilling",
    "BILLING_DONATION_MODEL": "billing.Donation",
}

Dashboard capabilities

Where the host project exposes compatible models, the Billing page can provide:

  • total revenue
  • recent revenue
  • active subscriptions/plans
  • donation information
  • plan breakdowns
  • daily income
  • MRR/ARR-oriented reporting
  • churn/failed-payment context where the host model exposes it

The integration is intentionally generic rather than hard-coded to a single billing application.

Security Center

Security Center brings application-facing security visibility into the same operational environment as analytics.

Login activity

The security layer can surface:

  • successful logins
  • failed login patterns
  • staff/privileged activity
  • login locations where available
  • authentication context
  • related security events

Active sessions

Where the host authentication/session model provides the required data, administrators can inspect active sessions and revoke them through the appropriate workflow.

IP blocklist

Security Center can maintain blocked IPs.

When SecurityBlockMiddleware is enabled, requests from blocked addresses can be denied before analytics recording.

Brute-force alerting

Configure:

PAXALIA_DASHBOARD = {
    "SECURITY_FAILED_LOGIN_THRESHOLD": 5,
    "SECURITY_FAILED_LOGIN_WINDOW_MINUTES": 15,
}

Crossing the configured threshold can generate a security alert.

CSP violation reporting

Browser CSP violations can be fed into the Security Center so policy failures can be investigated alongside application observability.

Security scorecard

The Security Scorecard presents configuration/posture findings from the package's supported security checks.

It is a visibility tool, not a replacement for an external security assessment.

The Security Overview is separate from this legacy scorecard surface: it uses explicit control states and actionable configuration details rather than reducing the administrator's security posture to one number.

Administrator authentication

Paxalia Dashboard administration is protected by a mandatory three-layer authentication contract:

Layer 1 — Host Django authentication
    password / configured backend
    rate limiting / brute-force protection
            ↓
Layer 2 — Mandatory 2FA
    Paxalia TOTP authenticator / recovery path
            ↓
Layer 3 — Authorized device credential
    WebAuthn challenge + signature verification
            ↓
Paxalia Dashboard Admin

The layers are enforced server-side. There is no ordinary dashboard setting that turns the three-layer administrator security model off. IP address, user-agent data, and browser fingerprints are context only; they are not treated as the identity of an authorized administrator device.

Defense-in-depth administrator controls

The mandatory administrator security contract is broader than the three credential layers:

1. Password
   └─ Django authentication + password validation

2. 2FA
   └─ django-otp TOTP or one-time recovery code

3. Device
   └─ WebAuthn challenge + credential signature verification

4. Rate limiting
   └─ login + 2FA + device ceremony limits

5. CSRF
   └─ Django CSRF middleware + CSRF-aware bundled JSON helper

6. Separate authentication
   └─ dedicated Paxalia SessionStore + scoped cookie

7. Secret path
   └─ deployment-specific private dashboard mount

Additional hardening surrounds the chain:

SecurityBlockMiddleware
        +
CSP / SecurityMiddleware
        +
honeypot integration
        +
sensitive-field redaction
        +
no-store protected responses
        +
package encryption/integrity
        +
bounded upload and log ingestion
        +
security/audit events

The dashboard's security tooling is therefore designed as a system rather than a single score.

Security Overview

Security Overview is a read-only diagnostic surface that reports the effective state of supported controls instead of turning security into a single opaque score. Checks can be reported as PASS, WARNING, DANGER, DISABLED, NOT CONFIGURED, or NOT APPLICABLE, with the current state, expected state, reason, configuration source, and a relevant action/page where one exists.

The checks cover the configured authentication and session stack, mandatory 2FA and enrollment, WebAuthn availability, HTTPS and cookie posture, CSRF and SecurityMiddleware, authentication/device rate limits, brute-force monitoring, ALLOWED_HOSTS, DEBUG, SECRET_KEY, CSP, persistent Paxalia logging and retention, protected package encryption, sensitive-field protection, admin-gate health, active administrator devices, and challenge/session policy.

Backup re-authentication

Sensitive backup downloads can require a recent password-authentication timestamp.

Paxalia Auth & Administrator Security

Paxalia Dashboard includes a standalone, override-friendly authentication experience for host Django projects. The main Paxalia application is not required; its authentication pages were used only as the UX/design reference for the Paxalia-branded presentation.

Public authentication surfaces

The package can provide:

  • Login
  • Sign Up
  • Password reset request
  • Password reset confirmation
  • Password change
  • Session-expired state
  • Access-denied state

These surfaces use Django's authentication, password validators, session framework, messages, CSRF protection, and configured user model rather than creating a second user/password database. Host projects can override the templates or route users to their existing authentication views.

Mandatory administrator authentication

The privileged Paxalia Dashboard flow is separate from ordinary public-site authentication. A public user can use the host application's normal login/signup flow; a dashboard administrator must complete all three security layers before a privileged Paxalia session is created.

Anonymous
  ↓
Paxalia Admin Login
  ↓
Layer 1: Django username/email + password
  ↓
Layer 2: confirmed TOTP / one-time recovery code
  ↓
Layer 3: authorized WebAuthn credential
  ↓
final Django/Paxalia administrator session

Intermediate authentication states are intentionally non-privileged. Reaching the password or 2FA step alone does not make the user an administrator for dashboard views, package operations, security settings, or protected APIs.

The seven security layers

Paxalia's final administrator protection model is intentionally described as seven layers because authentication credentials and deployment hardening solve different problems:

1. Password

The first layer uses the host project's configured Django user model. In isolated mode, Paxalia's default credential boundary deliberately uses Django's ModelBackend unless the host explicitly supplies another backend through AUTH_ISOLATED_AUTHENTICATION_BACKENDS.

The package does not create a parallel user/password database. Password validation remains Django's responsibility.

2. Mandatory 2FA

Every Paxalia administrator must have a confirmed TOTP device before normal privileged administration is permitted. Recovery codes provide a controlled recovery path without creating a password-only bypass.

3. Authorized device

Layer 3 uses WebAuthn. The server stores the public credential and safe authenticator metadata; the private credential remains with the authenticator.

Each ceremony uses a server-generated, short-lived, single-use challenge. Replay, expiry, wrong-user, and revoked-device cases are rejected.

A Paxalia Authorized Device Credential is not a guaranteed permanent hardware UUID. It represents an authorized credential that an administrator can register, name, review, and revoke.

4. Rate limiting

Authentication ceremonies are independently bounded:

Login
  8 attempts / 15 minutes

2FA
  5 attempts / 5 minutes

Device / WebAuthn
  5 attempts / 5 minutes

The package also surfaces broader failed-login thresholds through Security Center and keeps browser event ingestion bounded through the logging subsystem.

5. CSRF

State-changing browser operations remain behind Django CSRF protection. The authentication JavaScript includes the CSRF token in JSON POST requests used by the WebAuthn ceremony.

The secure deployment rule is simple:

CsrfViewMiddleware stays enabled.
Authentication views stay CSRF protected.
Do not solve integration problems by disabling CSRF.

6. Separate authentication boundaries

In the default isolated mode, the public website and Paxalia administrator authentication do not share the same session state.

The host website keeps its normal Django session while the dashboard uses:

paxalia_admin_session
        ↓
dedicated Django SessionStore
        ↓
dashboard-path cookie scope

This means:

host login      ≠      Paxalia admin login
host logout     ≠      Paxalia admin logout
host session    ≠      Paxalia admin session
host rotation   ≠      Paxalia admin rotation

The package still uses the configured Django session engine/backend, so isolation does not require a second identity database.

7. Secret dashboard path

The full administrator surface is mounted below a deployment-specific private path. Production configuration requires a 32–128 character URL-safe random segment and rejects common predictable administrator paths.

The path is defense in depth. It is deliberately not treated as an authentication mechanism.

Authentication lifecycle

The normal administrator lifecycle is:

GET private dashboard
        ↓
/auth/login/
        ↓
password accepted
        ↓
/auth/2fa/
        ↓
TOTP or one-time recovery code accepted
        ↓
/auth/device/
        ↓
WebAuthn credential accepted
        ↓
final Paxalia administrator session
        ↓
dashboard / Admin / Security / Packages

Logout returns to the Paxalia login surface and removes the dedicated administrator session. The host website session is left intact in isolated mode.

Layer 1 — primary authentication

Paxalia uses the host project's configured Django authentication backend and existing user model wherever possible. Login attempts are rate-limited by source and identifier, and important authentication events are sent through the existing Paxalia structured logging/security infrastructure. Unknown-account failures use safe generic messages and can be tracked through the existing failed-login observability.

Layer 2 — mandatory TOTP

Every administrator must have a confirmed TOTP device before normal Paxalia Dashboard administration is permitted. The package uses django-otp for the TOTP implementation and provides a Paxalia-branded enrollment and verification flow.

The enrollment flow is: complete primary authentication, enroll the authenticator, verify a current code, generate recovery codes, and continue to the authorized-device step. There is no normal "skip for now" path.

Recovery codes are generated with cryptographically secure randomness, stored as password hashes, individually consumed when used, revocable/regenerable, and never written to Paxalia logs.

Layer 3 — authorized device credential

Browser-based Layer 3 uses the maintained Python webauthn library and the WebAuthn browser API. Paxalia stores the public credential and safe authenticator metadata; the private credential remains with the authenticator. Each ceremony uses a server-generated, short-lived, single-use challenge. Replay, expiry, wrong-user, and revoked-credential cases fail.

The credential is a Paxalia Authorized Device Credential, not a guaranteed permanent hardware UUID. An administrator can register multiple credentials up to the configured active-device limit, name them, review safe metadata, and revoke them individually.

Device management

Security → Admin Devices provides:

  • device name
  • active/revoked/disabled state
  • registration time
  • last authentication time
  • authenticator/device type where available
  • attachment information where available
  • backup state where safely available
  • rename operation
  • individual revocation

Private keys, raw credential secrets, challenges, recovery codes, and other sensitive cryptographic material are never displayed as normal device data. Revocation is audited and invalidates future credential authentication; associated privileged sessions are also invalidated according to the configured session architecture.

Administrator sessions

Security → Admin Sessions shows privileged sessions recorded by the existing login-event infrastructure. Sessions can be revoked individually, all other sessions can be revoked, or all administrator sessions can be revoked. The privileged session remains valid only while the administrator is active, the confirmed second factor still exists, the authorized device credential remains active, the session has not expired, and the session has not been revoked.

WebAuthn deployment requirements

WebAuthn must use the actual deployed relying-party ID and browser origin. In production, the browser context must be HTTPS. WEBAUTHN_RP_ID and WEBAUTHN_ORIGIN can be explicitly configured for proxy/hosted deployments; otherwise the package derives them from the current request when safe. The dashboard does not silently fall back to password-only access if a secure WebAuthn ceremony cannot run.

Authentication events

The authentication and device flow uses the existing structured logging/audit architecture. Examples include:

admin_login_started
admin_login_failed
admin_login_rate_limited
admin_2fa_required
admin_2fa_success
admin_2fa_failed
admin_recovery_used
admin_device_challenge_failed
admin_device_authenticated
admin_device_rejected
admin_device_registered
admin_device_revoked
admin_device_renamed
admin_session_created
admin_all_sessions_revoked
admin_logout

Exact presentation can vary by logging surface, but these events remain within the existing Paxalia observability and Security Center architecture rather than creating a parallel security-event store. Authentication secrets, TOTP codes, recovery codes, private keys, and raw WebAuthn assertions are not logged.

Security configuration

The current settings expose policy details such as active-device limits, privileged-session lifetime, authentication and 2FA/device rate limits, challenge lifetime, WebAuthn relying-party configuration, recovery-code count, and authentication page branding. These settings configure implementation details; they do not disable the mandatory administrator security layers.

Paxalia Error Pages

The package ships production-oriented Paxalia 404 and 500 templates that can be used by a generic Django project. Their visual language is adapted from the broader Paxalia product reference while using Paxalia Dashboard's own theme tokens, typography, spacing, surfaces, and responsive shell.

404

The 404 page is a branded, responsive error surface with a lightweight glitch/CRT treatment, a safe return-home action, and a browser-history action. Dynamic request information is not reflected into the page without escaping.

500

The 500 page is intentionally production-safe. It does not expose exception details, tracebacks, SQL, filesystem paths, request headers, environment variables, or secrets. The technical event belongs in Paxalia Logs, where authorized administrators can investigate the correlated application/request event.

Error-page overrides

Host projects can override templates/404.html and templates/500.html using Django's normal template-loader precedence without editing the installed Paxalia package. Branding/home/support settings can be configured through the existing PAXALIA_DASHBOARD namespace.

Root URL configuration

Because Django resolves handler404 and handler500 from the project's root URLconf, wire the packaged handlers there:

handler404 = "paxalia.error_handlers.paxalia_404"
handler500 = "paxalia.error_handlers.paxalia_500"

This keeps the error implementation inside Paxalia while leaving root routing and template overrides under the host project's control.

DEBUG behavior

With production DEBUG=False, the packaged 500 page remains safe and user-facing. With DEBUG=True, Django's development exception machinery can still provide its normal development diagnostics to the developer; Paxalia does not treat DEBUG as a mechanism for bypassing administrator authentication.

Advanced Analytics

Goals

Goals represent target behaviors such as:

/signup/
purchase
form:submit

and can be used to measure completion.

Funnels

Funnels describe ordered steps such as:

landing page
    ↓
pricing
    ↓
signup
    ↓
checkout

Segments

Segments provide reusable audience definitions.

They can combine supported behavioral dimensions instead of forcing administrators to reproduce the same filters manually.

Campaigns

Campaign analysis works with campaign parameters and provides source/medium/campaign-oriented breakdowns.

Cohorts

Cohort analysis focuses on return behavior over time rather than one aggregate visitor total.

Annotations

Annotations connect events such as:

  • deployments
  • campaigns
  • incidents
  • launches
  • operational changes

to the analytics timeline.

Reporting & Sharing

Scheduled reports

The reporting subsystem can schedule high-level dashboard summaries and deliver them through configured email workflows.

The package can also generate PDF output where the optional PDF dependency is available.

Public share links

Protected read-only share links allow external stakeholders to view a selected dashboard surface without receiving staff credentials.

These links are intended to be narrowly scoped and protected.

Exports

Reporting workflows can generate:

  • CSV
  • JSON
  • PDF, where configured

The reporting path reuses existing dashboard computation rather than maintaining a separate analytics calculation engine.

Paxalia API

Paxalia provides an application-level API surface for supported analytics data.

API keys

API access uses scoped keys rather than one universal secret.

Scopes can distinguish ingestion/read behavior.

Browser event ingestion

The browser event collector uses the public event endpoint:

/api/paxalia/event/

The event path is intentionally separate from the private dashboard mount.

JS error ingestion

Real User Monitoring uses a corresponding public endpoint for browser JavaScript errors.

API documentation

The host deployment can expose protected API documentation/schema routes through its normal Django URL configuration.

Dependency Health

Dependency Health provides an operational view of the installed dependency closure.

It can help identify:

  • installed versions
  • direct dependencies
  • transitive dependencies
  • available release information where the configured environment permits comparison

The dashboard does not silently upgrade dependencies.

Dependency changes remain an explicit deployment decision.

Notifications & Alerts

Paxalia supports in-dashboard notifications plus optional external destinations.

Alert categories can include:

  • security
  • anomaly
  • uptime
  • deployment/operational events
  • supported system alerts

Optional delivery destinations include:

  • email
  • webhook endpoints
  • supported chat integrations

Alert delivery is deliberately best-effort.

A notification delivery failure should not turn the underlying application event into an application failure.

Multi-Site Analytics

Multiple domains can be represented by Site records.

Requests are resolved by hostname and associated with active sites.

Configure:

PAXALIA_DASHBOARD = {
    "AUTO_CREATE_SITES": False,
}

Automatic site creation is disabled by default.

This avoids silently creating database rows for unexpected hostnames.

Release Center

The Release Center provides release and deployment context.

Deployment tracking can connect application releases to analytics annotations.

Example:

python manage.py record_deployment \
    --version "$(git rev-parse --short HEAD)" \
    --notes "the deployed release"

The result is a deployment record plus a matching chart annotation.

Release artifact management remains separate from deployment event tracking.

Paxalia Logging / Observability

The platform adds a canonical persistent logging and observability subsystem under paxalia.logging.

This is one of the major differences between the earlier analytics-only architecture and the platform.

The logging system does not replace:

  • analytics
  • RUM
  • Security Center
  • server metrics
  • existing application logging

Instead it creates a shared structured observability layer that can connect those sources when appropriate.

Core architecture

Python / Django loggers
        │
        ├── Paxalia logging handler
        │
        └── paxalia.log(...)
                 │
                 ▼
        normalized event context
                 │
                 ├── redaction
                 ├── fingerprinting
                 ├── grouping
                 ├── deduplication
                 └── bounded persistence
                 │
                 ▼
         PaxaliaLogEvent
                 │
                 ├── PaxaliaLogGroup
                 ├── Logs dashboard
                 ├── Application Logs
                 ├── Login Activity
                 ├── Log Detail
                 └── exports / retention

Direct application logging

The package exposes a simple application-facing entry point:

import paxalia

paxalia.log(
    "Workspace synchronization failed",
    level="ERROR",
    category="application.sync",
    action="sync_failed",
    metadata={
        "workspace_id": "...",
    },
)

The helper uses the same canonical logging pipeline as standard Python/Django logs.

Standard logging capture

When enabled, ordinary logger calls can be captured without changing application code:

import logging

logger = logging.getLogger(__name__)

logger.error(
    "Synchronization failed",
    extra={
        "category": "application.sync",
        "action": "sync_failed",
    },
)

Paxalia normalizes the record before persistence.

Request lifecycle logging

PaxaliaLoggingMiddleware can provide:

  • request IDs
  • response-status events
  • duration
  • request path
  • method
  • site
  • session context
  • authenticated user context
  • correlation/trace identifiers

Configure:

MIDDLEWARE = [
    # ...
    "paxalia.logging.middleware.PaxaliaLoggingMiddleware",
]

The middleware is designed for request context.

Paxalia logging also supports request-less events from:

  • background jobs
  • startup code
  • CLI commands
  • scheduled management commands
  • direct application logging

Event context

A stored event can contain structured fields for:

  • severity
  • source
  • category
  • action
  • logger name
  • message
  • exception type
  • stack trace
  • module
  • file
  • line number
  • function
  • session ID
  • request ID
  • correlation ID
  • trace ID
  • request method
  • request path
  • response status
  • duration
  • site
  • traffic type
  • bot category
  • user ID
  • user display information
  • admin marker
  • IP context where configured
  • User-Agent
  • browser
  • operating system
  • device
  • process ID
  • thread name
  • host
  • environment
  • release
  • structured metadata
  • sensitive-data state

Not every event has every value.

Fingerprints and grouping

Paxalia can calculate a stable fingerprint from structural event characteristics.

Related events can be grouped and summarized through:

  • first-seen time
  • last-seen time
  • occurrence count
  • suppressed count
  • sample count
  • grouping window
  • representative metadata

This lets an administrator see:

1 underlying problem
    ↓
4,812 occurrences
    ↓
5 retained representative samples

instead of manually opening thousands of duplicate log rows.

Deduplication

Handler-topology duplication is guarded so the same record is not persisted repeatedly simply because it passed through multiple supported logging paths.

Exception capture

The logging layer records:

  • exception type
  • normalized message
  • stack trace

Stack/message lengths are bounded through configuration.

Redaction

Sensitive values are sanitized before persistent presentation/storage according to the package's redaction policy.

Common credential classes include:

password
token
access_token
refresh_token
secret
api_key
private_key
authorization
cookie
credential
session key
encryption key

Host projects can extend the sensitive-key configuration.

The objective is:

useful debugging context
        +
low probability of credential persistence

not simply deleting every form of structured metadata.

Browser observability

The browser-side RUM/error system can feed relevant errors into the canonical logging/investigation workflow.

Log dashboard

The Logs page supports investigation through:

  • date filtering
  • severity filtering
  • source/result filters
  • search
  • structured event rows
  • pagination
  • auto-refresh
  • detail navigation
  • related-event discovery

Less frequently used controls are kept behind secondary filtering so the main operational surface stays calm.

Log detail

The detailed event surface is built for incident investigation rather than only showing a single message.

It can expose:

  • event identity
  • request/network context
  • client/browser context
  • runtime context
  • grouping information
  • structured metadata
  • exception details
  • stack traces
  • related events

A sanitized Copy for AI workflow can prepare structured incident context for external debugging or AI-assisted analysis.

The copied context is intentionally sanitized rather than treating the raw event database as a safe prompt source.

Login activity

Authentication-related observability can be inspected independently through the Login Activity dashboard.

Failed-login identifiers can be privacy-controlled.

Retention

Current logging retention configuration is category-specific:

PAXALIA_DASHBOARD = {
    "LOG_RETENTION_DAYS": {
        "system": 30,
        "request": 30,
        "browser": 30,
        "application": 30,
        "login": 180,
        "security": 180,
        "group": 90,
    },
}

Run a dry run first:

python manage.py paxalia_logs_prune --dry-run

Then schedule pruning:

python manage.py paxalia_logs_prune

Logging-specific safety properties

The observability system is designed so that:

  • sensitive values are redacted
  • payload sizes are bounded
  • browser event rates are bounded
  • metadata sizes are bounded
  • identifiers are normalized
  • grouping state is bounded
  • logging failures do not break the primary application request path
  • request-less logging remains supported

Paxalia Admin & Packages

The platform includes a full Paxalia Admin and the Paxalia Package Center.

Detailed implementation notes also live in:

docs/PAXALIA_ADMIN_PACKAGES.md

Paxalia Admin philosophy

Paxalia Admin is not a replacement for Django Admin architecture.

Its model flow is:

Django Admin registry
        ↓
PaxaliaAdminRegistry
        ↓
model definition / adapter / capabilities
        ↓
query / services / forms
        ↓
Paxalia Admin views
        ↓
Paxalia dashboard UI

Django remains the source of truth for:

  • model registration
  • ModelAdmin configuration
  • permissions
  • model forms
  • supported custom actions
  • inline definitions

Django Admin remains the fallback for exotic behavior that cannot safely be rendered by Paxalia Admin.

Model discovery

The Admin workspace discovers models from Django's registered ModelAdmin registry.

It can expose metadata such as:

  • application label
  • model label
  • verbose name
  • verbose plural name
  • capabilities
  • search support
  • filter support
  • ordering
  • list display
  • list editable
  • actions
  • relationship fields
  • inline definitions
  • localization capability
  • identity fields
  • sensitive fields
  • protected behavior

The registry is dynamic.

Host model names are not hard-coded into Paxalia.

Models browser

The Models page is intentionally catalog-oriented.

It provides:

  • application groups
  • searchable models
  • application collapse/expand
  • compact model cards
  • capability metadata
  • responsive layouts
  • meaningful empty states

Application groups expose accessible toggle controls with aria-expanded and aria-controls.

Model search can match:

  • verbose model name
  • model label
  • application label
  • application verbose name
  • visible model metadata

Changelists

Paxalia Admin supports normal record browsing with:

  • list display
  • sorting
  • search
  • filters
  • pagination
  • date hierarchy where supported
  • query-string state preservation
  • record selection
  • supported list-editable formsets
  • CSV/JSON data workflows where exposed
  • optimized relationship loading where possible

List editable

When the registered ModelAdmin uses Django's list_editable, Paxalia Admin can reuse the corresponding formset behavior.

The Django management-form prefix semantics are preserved so editable formsets behave like Django expects.

CRUD

The generic Admin surface supports:

Create
  ↓
Django ModelForm
  ↓
validate
  ↓
save
  ↓
audit

Read
  ↓
safe presentation
  ↓
sensitive masking
  ↓
relationship inspection

Update
  ↓
permission check
  ↓
ModelForm
  ↓
validate
  ↓
save
  ↓
audit

Delete
  ↓
permission check
  ↓
deletion collector
  ↓
preview
  ↓
confirm
  ↓
delete
  ↓
audit

Permissions

Paxalia Admin uses Django permission semantics.

Access is not granted simply because a model is registered.

The current architecture checks:

  • staff access
  • model-level permissions
  • object-level permission hooks where available
  • add/change/delete capabilities
  • action permissions
  • localization permissions
  • package permissions

Sensitive fields

Sensitive-field configuration is applied at the display layer and package layer where applicable.

Examples:

password
token
access_token
refresh_token
client_secret
api_key
private_key
authorization
cookie
secret_key
encryption_key

Sensitive values should not appear as normal list/detail values.

Protected workflows can require stronger controls rather than simply showing the value.

Relationships

Paxalia Admin recognizes Django relationship structures including:

  • ForeignKey
  • OneToOneField
  • ManyToManyField
  • reverse relations
  • self-references
  • supported inline relations

The query layer can optimize common relationship loading.

Inline admins

The Admin diagnostics inspect registered inline definitions.

Supported inline presentation uses Django's existing TabularInline/StackedInline concepts where the generic Paxalia surface can safely reproduce them.

Exotic inline behavior remains eligible for Django Admin fallback.

Actions

Normal Django custom actions can be surfaced through the Paxalia action workflow.

Permission checks remain enforced before execution.

Action failures are surfaced rather than silently treated as success.

Statistics

Model statistics can include, where the model makes them detectable:

  • record totals
  • created counts
  • updated counts
  • related counts
  • choice distributions
  • localization completeness

The exact statistics are model-dependent and are never hard-coded around a particular host application.

History and audit

Paxalia Admin can show:

  • history
  • recent changes
  • actor context
  • timestamps
  • object context
  • Django admin log entries
  • Paxalia security audit events

Sensitive values remain redacted.

Localization workspace

Translatable models can expose a localization workspace.

The workflow is:

discover translation system
        ↓
discover configured languages
        ↓
inspect completeness
        ↓
choose language
        ↓
edit supported translation fields
        ↓
save through model translation API

Languages come from Django configuration.

The Admin does not hard-code a fixed number of language tabs.

Package Center

Package operations are protected by the same administrator security boundary as the rest of Paxalia. Export/import, protected models, encrypted packages, and retry-package workflows run only inside the privileged dashboard context.

The package UI is available from Paxalia Admin and is divided into deliberate workflows:

Package Center
    ├── Export
    ├── Import
    └── History

Export and import screens intentionally separate:

Scope
Models
Filters
Options
Security
Action

rather than presenting every control as one giant form.

Paxalia Package Format

.paxalia is a model-aware logical package format.

It is not a raw database dump.

Conceptually:

ordinary package

package.paxalia
├── manifest.json
├── integrity.json
└── data.json

and an encrypted package can use the encrypted data member:

package.paxalia
├── manifest.json
├── integrity.json
└── data.enc

The exact package internals are versioned by the package format itself.

Manifest

The manifest records package metadata required for validation and compatibility.

It allows the reader to establish:

  • package format version
  • logical package metadata
  • model scope
  • object/relationship context
  • translation information where included
  • encryption state

Integrity

Package contents are integrity-checked with SHA-256 hashes.

Tampered package data must fail validation.

Archive safety

The package reader validates archive structure before database mutation.

Security checks include defenses for:

  • duplicate ZIP members
  • path traversal
  • invalid archive structure
  • unsupported versions
  • invalid encryption metadata
  • size/count limits
  • malformed records
  • malformed relationships

The package file extension itself is not treated as a security boundary.

Serialization

The exporter handles supported Django/Python values such as:

  • UUID
  • datetime
  • date
  • time
  • Decimal
  • timedelta
  • Path
  • bytes
  • JSON-compatible structures
  • Django FieldFile logical paths
  • lazy translation values
  • relationship identities

The serializer does not blindly call json.dumps() on arbitrary model values.

Unsupported or unexpected data is treated as an explicit export problem where required rather than silently presented as a complete successful package.

Identity resolution

Imports use configured identity fields where appropriate.

Examples include:

  • primary key
  • unique field
  • slug
  • username
  • email
  • configured field combinations

Identity resolution occurs before relationship restoration.

New records normally receive new Django IDs unless the package strategy explicitly requires identity restoration.

Relationships

Paxalia packages can preserve supported:

  • ForeignKey relationships
  • OneToOne relationships
  • ManyToMany relationships
  • self-references
  • supported translation relationships

Relationship restoration is identity-aware and does not depend on archive row order.

Conflicts

The current default allowed strategies are:

update
skip

The package engine validates the selected conflict strategy against configured policy.

Import preview

The Import workflow can preview:

  • model count
  • record count
  • creates
  • updates
  • skips
  • potential failures
  • relationships
  • translations
  • encryption state
  • validation state

The preview is generated from actual package validation and planning.

It is not an illustrative hard-coded result.

Dry run

A dry run validates and plans without permanent database mutation.

It can detect:

  • malformed records
  • identity conflicts
  • missing relationships
  • incompatible fields
  • translation problems
  • permissions
  • size/count limits
  • encryption requirements

Atomic imports

Atomic import uses Django transactions according to the configured scope.

If required work fails, the configured transaction boundary can roll back mutations.

Partial imports

Partial import allows independent valid work to remain committed while failed work is isolated and reported.

A relationship-dependent operation should not be called a successful partial import when the dependency graph makes the resulting data invalid.

Failure reporting

Failures are structured around:

  • model
  • object identity
  • field
  • relationship
  • translation
  • exception category
  • safe failure reason

Secret material should not be included.

Retry packages

Failed subsets can be packaged for retry where practical.

The retry package preserves the relevant operation context without forcing an administrator to reconstruct the failed data manually.

Protected models

Configured protected models can require encryption:

PAXALIA_DASHBOARD = {
    "PACKAGE_REQUIRE_ENCRYPTION_FOR_PROTECTED": True,
}

This policy is enforced by the package engine, not only by the UI.

Encryption

Paxalia package encryption uses authenticated encryption via the optional cryptography dependency.

The current security module uses:

AES-256-GCM
PBKDF2-HMAC-SHA256

with bounded/validated KDF parameters.

Wrong passwords and tampering produce package-security failures rather than partial plaintext processing.

Package limits

Current defaults include:

PAXALIA_DASHBOARD = {
    "PACKAGE_MAX_FILE_SIZE_MB": 100,
    "PACKAGE_MAX_OBJECTS": 10000,
    "PACKAGE_MAX_RELATIONS": 50000,
}

These limits are intended to keep administrative package operations predictable.

CLI validation

Validate:

python manage.py paxalia_package_validate export.paxalia

Inspect:

python manage.py paxalia_package_inspect export.paxalia

Encrypted package inspection requires the appropriate password input according to the command's options.

Important distinction: package vs backup

Use physical backups for:

  • disaster recovery
  • database restoration
  • server recovery
  • infrastructure migration
  • full system restore

Use .paxalia packages for:

  • logical application-data transfer
  • selected model migration
  • model-aware export/import
  • translation transfer
  • environment-to-environment content movement
  • controlled administrative data exchange

Do not use a logical package as your only disaster-recovery mechanism.

Operational Commands

Paxalia contains management commands for analytics, operations, logging, Admin diagnostics, package validation, and maintenance.

Analytics and operational commands

python manage.py aggregate_daily_stats
python manage.py backfill_pageview_bot_category
python manage.py backfill_pageview_is_api
python manage.py check_uptime
python manage.py cleanup_uploads
python manage.py create_backup
python manage.py detect_anomalies
python manage.py import_bot_paths /path/to/bot_paths.txt
python manage.py prune_analytics_data
python manage.py prune_security_logs
python manage.py record_deployment --version "$(git rev-parse --short HEAD)"
python manage.py record_server_metrics
python manage.py seed_analytics
python manage.py send_scheduled_reports

Logging diagnostics and retention

python manage.py paxalia_logs_test --keep
python manage.py paxalia_logs_prune --dry-run
python manage.py paxalia_logs_prune

Dashboard diagnostics

python manage.py paxalia_dashboard_test --keep --no-ui
python manage.py paxalia_dashboard_test --keep

Administrator authentication/security tests

The security/authentication suite can be run directly:

python manage.py test paxalia.test_security_auth -v 2
python manage.py test paxalia.test_security_cleanup_fix22 -v 2
python manage.py test paxalia.test_security_ux_fix21 -v 2

The focused security tests cover the password/2FA/device flow, isolated-session semantics, logout behavior, rate-limit enforcement, WebAuthn ceremony handling, and security UI contracts.

Paxalia Admin diagnostics

python manage.py paxalia_admin_test

The Admin diagnostics check areas such as:

  • Django Admin registry
  • Admin enabled state
  • registered model discovery
  • model configuration
  • ModelAdmin compatibility
  • list-editable support
  • deletion preview compatibility
  • relationship and inline discovery
  • history routes
  • sensitive-field policy
  • hardening settings

Diagnostic model counts are intentionally dynamic.

Do not hard-code values from one host environment into the package.

Package inspection

python manage.py paxalia_package_validate export.paxalia
python manage.py paxalia_package_inspect export.paxalia

Suggested schedules

Daily aggregation:

0 0 * * * cd /path/to/project && python manage.py aggregate_daily_stats

Server history:

* * * * * cd /path/to/project && python manage.py record_server_metrics

Uptime checks:

* * * * * cd /path/to/project && python manage.py check_uptime

Anomaly detection:

10 * * * * cd /path/to/project && python manage.py detect_anomalies

Analytics retention:

0 3 * * * cd /path/to/project && python manage.py prune_analytics_data

Security log retention:

20 3 * * * cd /path/to/project && python manage.py prune_security_logs

Paxalia log retention:

30 3 * * * cd /path/to/project && python manage.py paxalia_logs_prune

Security & Privacy Model

Paxalia is designed to keep data on the host application.

That does not mean "privacy automatically solved."

The host project still controls:

  • database access
  • operating system security
  • reverse proxy
  • authentication
  • administrator accounts
  • backups
  • network policy
  • retention choices
  • proxy trust
  • email/webhook destinations
  • access to exported files

Application-level security principles

Paxalia uses:

  • Django authentication
  • staff checks
  • Django permissions
  • object-level ModelAdmin permission hooks where available
  • CSRF protection
  • sensitive-field redaction
  • no-store handling for protected responses where configured
  • package structural validation
  • package integrity checks
  • package encryption requirements
  • ZIP archive safety controls
  • bounded upload/package limits
  • audit/security events

Secret dashboard paths

The dashboard can be mounted at a private path.

This is useful as a defense-in-depth measure.

It must not be treated as an authentication mechanism by itself.

For the final v4.0.0 deployment model, the private path is configured through DASHBOARD_URL and, in production, is validated as a 32–128 character URL-safe random segment.

All privileged dashboard routes and the Paxalia administrator authentication lifecycle can live beneath that same private mount:

<secret-path>/
├── auth/
├── security/
├── admin/
├── logs/
├── packages/
└── dashboard/

The browser-facing public application can keep normal authentication and public ingestion routes outside this mount.

Public ingestion endpoints

Browser event ingestion is intentionally public because visitors send anonymous telemetry to it.

Public ingestion endpoints must therefore validate and bound input on the server.

Proxy trust

Only enable forwarded-IP trust behind a controlled proxy infrastructure.

Logging privacy

Persistent observability makes debugging easier, but it also creates another sensitive data store.

The logging system therefore:

  • redacts credential-like fields
  • bounds message and stack sizes
  • bounds metadata
  • bounds browser event rates
  • supports retention policies
  • distinguishes diagnostic context from secrets
  • supports privacy-aware failed-login identifier handling

Admin privacy

Paxalia Admin is designed to avoid displaying configured sensitive fields as normal values.

Protected values should not be exposed simply because an administrator can browse the model.

Package privacy

Normal exports omit configured sensitive fields.

Protected-model export can require encryption.

Package failure reports must not expose secret material.

Backups

Physical backups contain whatever the configured backup scope includes.

Treat them as highly sensitive infrastructure artifacts and protect their storage and transport accordingly.

What Paxalia does not do

Paxalia does not:

  • replace your OS firewall
  • rotate all application credentials for you
  • verify crawler identity through a live IP-range lookup
  • replace a dedicated WAF
  • replace a dedicated SIEM
  • automatically upgrade dependencies
  • provision your Redis/Celery/PostgreSQL infrastructure
  • operate your mail server
  • replace a physical disaster-recovery strategy
  • certify legal compliance

Production principle

Use Paxalia as an application-level observability, analytics, administration, and security layer alongside your normal infrastructure controls.

Paxalia and Django

Paxalia Dashboard is an application package for Django, not a replacement for Django.

Responsibility Django / host project Paxalia Dashboard
ORM and database models Authoritative Integrates with them
Authentication Authoritative Reuses host authentication and adds the mandatory admin verification layers
Model permissions Authoritative Reuses Django permission and ModelAdmin hooks
URL routing Authoritative Adds dashboard/package routes
Business logic Authoritative Observes and administrates without owning host business rules
Django Admin registry Authoritative Uses it as the source of truth for generic Admin
Analytics Host/application data Provides the analytics layer
Structured application logging Host/Python logging APIs Provides persistent observability and investigation
Server/runtime telemetry Host environment Provides application-facing monitoring
Logical data portability Host data Provides .paxalia package workflows
Physical backups Host infrastructure Provides complementary backup-management utilities
Deployment Host infrastructure/CI Records deployment context
Final operational authority Host project Remains with the host project

This separation is deliberate. Paxalia becomes powerful by integrating with Django rather than by trying to replace the framework it runs inside.

Architecture & Extensibility

Paxalia is intentionally modular.

Analytics architecture

HTTP request
    ↓
middleware
    ↓
classification / site resolution
    ↓
persistent analytics models
    ↓
aggregation / reporting
    ↓
dashboard views
    ↓
browser UI

Logging architecture

stdlib / Django logging
        +
paxalia.log()
        ↓
normalization
        ↓
context
        ↓
redaction
        ↓
fingerprint / grouping
        ↓
persistent observability
        ↓
logs / audit / investigation

Admin architecture

django.contrib.admin registry
        ↓
PaxaliaAdminRegistry
        ↓
adapter / definition / capabilities
        ↓
permissions
        ↓
query + services + forms
        ↓
views
        ↓
Paxalia Admin UI

Package architecture

selection / queryset
        ↓
generic serializer
        ↓
identity map
        ↓
relationship data
        ↓
translation data
        ↓
manifest + integrity
        ↓
optional authenticated encryption
        ↓
.paxalia archive

Extension philosophy

Host applications can extend Paxalia through configuration and their existing Django architecture.

Good extension points include:

  • ModelAdmin registration
  • model-specific identity fields
  • sensitive-field configuration
  • dashboard section configuration
  • application log adapters
  • billing models
  • Celery app path
  • site records
  • translation models
  • theme configuration

Avoid hard-coding host application models into Paxalia itself.

Final v4.0.0 Security Checklist

Before exposing Paxalia Dashboard to real users, verify the deployment as one complete boundary:

[ ] Password authentication is active
[ ] Administrator accounts are recognized by the configured admin policy
[ ] TOTP enrollment is confirmed
[ ] Recovery codes are generated and stored safely
[ ] At least one authorized WebAuthn device is registered
[ ] Device revocation is tested
[ ] Login / 2FA / device rate limits are configured
[ ] Django CSRF middleware is enabled
[ ] Paxalia administrator session isolation is enabled
[ ] The isolated administrator cookie is scoped to the private dashboard path
[ ] Production DASHBOARD_URL is a long random segment
[ ] WebAuthn RP ID and origin match the deployed HTTPS origin
[ ] ALLOWED_HOSTS is configured correctly
[ ] DEBUG=False in production
[ ] SECRET_KEY is configured securely
[ ] CSP/SecurityMiddleware remain enabled
[ ] Sensitive fields are protected in Admin
[ ] Security Overview reports the expected posture
[ ] Backup downloads use the configured re-authentication policy
[ ] Authentication and security events are visible in Paxalia observability

A secret path, a password, 2FA, or WebAuthn by itself is not the complete security model. The package is designed so these controls reinforce one another.

Project Structure

The security/authentication layer is organized into separate policy, rate-limit, health-diagnostic, WebAuthn, and view modules:

The v4 security/authentication implementation additionally includes dedicated session-isolation and host-authentication- bridge modules. The complete tree below is intentionally kept in the README so contributors can see the full package layout rather than a reduced feature summary:

paxalia/
├── admin_security.py
├── error_handlers.py
├── security_health.py
├── security_rate_limit.py
├── webauthn_services.py
├── views/
│   ├── auth.py
│   ├── admin_security.py
│   ├── mfa.py
│   └── security.py
├── migrations/
│   └── 0022_paxalia_admin_security.py
└── templates/
    ├── 404.html
    ├── 500.html
    ├── paxalia/
    │   ├── security_overview.html
    │   ├── security_authentication.html
    │   ├── admin_devices.html
    │   └── admin_sessions.html
    └── paxalia_auth/
        ├── login.html
        ├── signup.html
        ├── forgot-password.html
        ├── reset-password.html
        ├── password_change.html
        ├── two-factor.html
        ├── two-factor-setup.html
        ├── recovery-codes.html
        ├── device-register.html
        └── device-verify.html

A representative source tree looks like:

paxalia-dashboard/


├── paxalia
│   ├── admin_auth_middleware.py
│   ├── admin_center
│   │   ├── adapter.py
│   │   ├── __init__.py
│   │   ├── package_views.py
│   │   ├── permissions.py
│   │   ├── query.py
│   │   ├── registry.py
│   │   ├── services.py
│   │   ├── urls.py
│   │   ├── utils.py
│   │   └── views.py
│   ├── admin.py
│   ├── admin_security.py
│   ├── alerts.py
│   ├── anomalies.py
│   ├── api_keys.py
│   ├── apps.py
│   ├── auth_middleware.py
│   ├── auth.py
│   ├── bot_classification.py
│   ├── bots_paths.txt
│   ├── chat_ops.py
│   ├── cohorts.py
│   ├── compliance.py
│   ├── conf_uploads.py
│   ├── context_processors.py
│   ├── conversions.py
│   ├── data_import.py
│   ├── error_handlers.py
│   ├── forms.py
│   ├── geoip
│   │   ├── GeoLite2-ASN.mmdb
│   │   ├── GeoLite2-City.mmdb
│   │   └── GeoLite2-Country.mmdb
│   ├── __init__.py
│   ├── locale
│   │   ├── ar
│   │   │   └── LC_MESSAGES
│   │   │       ├── django.mo
│   │   │       └── django.po
│   │   ├── en
│   │   │   └── LC_MESSAGES
│   │   │       └── django.po
│   │   ├── es
│   │   │   └── LC_MESSAGES
│   │   │       ├── django.mo
│   │   │       └── django.po
│   │   ├── pt-br
│   │   │   └── LC_MESSAGES
│   │   │       ├── django.mo
│   │   │       └── django.po
│   │   └── zh-hans
│   │       └── LC_MESSAGES
│   │           ├── django.mo
│   │           └── django.po
│   ├── logging
│   │   ├── application.py
│   │   ├── context.py
│   │   ├── fingerprint.py
│   │   ├── handler.py
│   │   ├── __init__.py
│   │   ├── middleware.py
│   │   ├── redaction.py
│   │   └── services.py
│   ├── management
│   │   └── commands
│   │       ├── aggregate_daily_stats.py
│   │       ├── backfill_pageview_bot_category.py
│   │       ├── backfill_pageview_is_api.py
│   │       ├── check_uptime.py
│   │       ├── cleanup_uploads.py
│   │       ├── create_backup.py
│   │       ├── detect_anomalies.py
│   │       ├── import_bot_paths.py
│   │       ├── paxalia_admin_test.py
│   │       ├── paxalia_dashboard_test.py
│   │       ├── paxalia_logs_prune.py
│   │       ├── paxalia_logs_test.py
│   │       ├── paxalia_package_inspect.py
│   │       ├── paxalia_package_validate.py
│   │       ├── prune_analytics_data.py
│   │       ├── prune_security_logs.py
│   │       ├── record_deployment.py
│   │       ├── record_server_metrics.py
│   │       ├── seed_analytics.py
│   │       └── send_scheduled_reports.py
│   ├── middleware.py
│   ├── migrations
│   │   ├── 0001_initial.py
│   │   ├── 0002_security_center.py
│   │   ├── 0003_csp_violations.py
│   │   ├── 0004_pageview_is_api.py
│   │   ├── 0005_flip_anonymize_ip_default.py
│   │   ├── 0006_multisite.py
│   │   ├── 0007_goals_funnels_segments_annotations.py
│   │   ├── 0008_dashboard_access_permissions.py
│   │   ├── 0009_paxalia_api_key.py
│   │   ├── 0010_reporting_sharing.py
│   │   ├── 0011_notifications.py
│   │   ├── 0012_bot_category.py
│   │   ├── 0013_js_error.py
│   │   ├── 0014_uptime_monitoring.py
│   │   ├── 0015_ops_monitoring.py
│   │   ├── 0016_compliance_permission.py
│   │   ├── 0017_data_import.py
│   │   ├── 0018_fix_dailysitestats_duplicates.py
│   │   ├── 0019_sharelink_password_hash.py
│   │   ├── 0020_paxalia_observability.py
│   │   ├── 0021_remove_loginevent_paxalia_log_is_ad_8ef5a0_idx_and_more.py
│   │   ├── 0022_paxalia_admin_security.py
│   │   └── __init__.py
│   ├── models.py
│   ├── packages
│   │   ├── engine.py
│   │   ├── format.py
│   │   ├── __init__.py
│   │   ├── localization.py
│   │   └── security.py
│   ├── permissions.py
│   ├── queue_monitor.py
│   ├── report_delivery.py
│   ├── reporting.py
│   ├── requirements.txt
│   ├── revenue.py
│   ├── rum.py
│   ├── security_audit.py
│   ├── security_health.py
│   ├── security_rate_limit.py
│   ├── security_scorecard.py
│   ├── segments.py
│   ├── settings.py
│   ├── signals.py
│   ├── static
│   │   └── paxalia
│   │       ├── icons
│   │       │   ├── archive
│   │       │   │   ├── icon-file-text.svg
│   │       │   │   ├── icon-global.svg
│   │       │   │   └── icon-time-spendin.svg
│   │       │   ├── brand
│   │       │   │   ├── icon-brand.png
│   │       │   │   └── icon-brand.svg
│   │       │   ├── dependencies.js
│   │       │   ├── realtime.js
│   │       │   ├── sidebar.js
│   │       │   ├── ui
│   │       │   │   ├── icon-bar-chart.svg
│   │       │   │   ├── icon-bot.svg
│   │       │   │   ├── icon-cpu.svg
│   │       │   │   ├── icon-download.svg
│   │       │   │   ├── icon-harddisk.svg
│   │       │   │   ├── icon-key.svg
│   │       │   │   ├── icon-layers.svg
│   │       │   │   ├── icon-memory.svg
│   │       │   │   ├── icon-network.svg
│   │       │   │   ├── icon-overview.svg
│   │       │   │   └── icon-server.svg
│   │       │   └── ui-multi
│   │       │       ├── icon-cloud-uploading.svg
│   │       │       └── icon-setting.svg
│   │       ├── scripts
│   │       │   ├── admin-center.js
│   │       │   ├── admin-overview.js
│   │       │   ├── analytics-events.js
│   │       │   ├── api.js
│   │       │   ├── auth.js
│   │       │   ├── backups.js
│   │       │   ├── billing-chart.js
│   │       │   ├── bots.js
│   │       │   ├── chart.umd.js
│   │       │   ├── d3.v3.min.js
│   │       │   ├── datamaps.world.min.js
│   │       │   ├── dependencies.js
│   │       │   ├── error.js
│   │       │   ├── events-chart.js
│   │       │   ├── filter-bar.js
│   │       │   ├── geography-map.js
│   │       │   ├── language-manager.js
│   │       │   ├── logging-filter.js
│   │       │   ├── logs.js
│   │       │   ├── overview.js
│   │       │   ├── page-detail.js
│   │       │   ├── realtime.js
│   │       │   ├── security.js
│   │       │   ├── server
│   │       │   │   ├── cpu.js
│   │       │   │   ├── disk.js
│   │       │   │   ├── memory.js
│   │       │   │   ├── network.js
│   │       │   │   ├── overview.js
│   │       │   │   ├── processes.js
│   │       │   │   └── services.js
│   │       │   ├── sidebar.js
│   │       │   ├── theme-manager.js
│   │       │   ├── topojson.v1.min.js
│   │       │   ├── upload-widget.js
│   │       │   └── webauthn.js
│   │       └── styles
│   │           ├── base.css
│   │           ├── components
│   │           │   ├── about.css
│   │           │   ├── admin.css
│   │           │   ├── auth.css
│   │           │   ├── backup.css
│   │           │   ├── buttons.css
│   │           │   ├── charts.css
│   │           │   ├── dependencies.css
│   │           │   ├── error.css
│   │           │   ├── export-btn.css
│   │           │   ├── filter-bar.css
│   │           │   ├── icon.css
│   │           │   ├── logging.css
│   │           │   ├── menu.css
│   │           │   ├── notifications.css
│   │           │   ├── release-center.css
│   │           │   ├── rum.css
│   │           │   ├── security.css
│   │           │   ├── server.css
│   │           │   ├── settings-form.css
│   │           │   ├── sidebar.css
│   │           │   ├── stat-cards.css
│   │           │   ├── tables.css
│   │           │   ├── topbar.css
│   │           │   ├── typography.css
│   │           │   └── upload.css
│   │           ├── dashboard-refinements.css
│   │           ├── layout.css
│   │           ├── themes.css
│   │           └── tokens.css
│   ├── templates
│   │   ├── 404.html
│   │   ├── 500.html
│   │   ├── paxalia
│   │   │   ├── about.html
│   │   │   ├── admin
│   │   │   │   ├── audit.html
│   │   │   │   ├── bulk_delete.html
│   │   │   │   ├── delete_confirmation.html
│   │   │   │   ├── history.html
│   │   │   │   ├── home.html
│   │   │   │   ├── model_list.html
│   │   │   │   ├── model_localization.html
│   │   │   │   ├── model_overview.html
│   │   │   │   ├── models.html
│   │   │   │   ├── model_stats.html
│   │   │   │   ├── object_detail.html
│   │   │   │   ├── object_form.html
│   │   │   │   ├── package_center.html
│   │   │   │   ├── package_export_center.html
│   │   │   │   ├── package_export.html
│   │   │   │   ├── package_history.html
│   │   │   │   ├── package_import_center.html
│   │   │   │   ├── package_import.html
│   │   │   │   └── package_result.html
│   │   │   ├── admin_devices.html
│   │   │   ├── admin_overview.html
│   │   │   ├── admin_sessions.html
│   │   │   ├── annotations.html
│   │   │   ├── api_docs.html
│   │   │   ├── api.html
│   │   │   ├── api_keys.html
│   │   │   ├── application_logs.html
│   │   │   ├── auth_base.html
│   │   │   ├── backup_reauth.html
│   │   │   ├── backups.html
│   │   │   ├── base.html
│   │   │   ├── billing.html
│   │   │   ├── bots.html
│   │   │   ├── broken_links.html
│   │   │   ├── campaigns.html
│   │   │   ├── cohorts.html
│   │   │   ├── compliance.html
│   │   │   ├── dashboard.html
│   │   │   ├── data_import.html
│   │   │   ├── dependencies.html
│   │   │   ├── email
│   │   │   │   └── report_digest.html
│   │   │   ├── error_base.html
│   │   │   ├── events.html
│   │   │   ├── funnels.html
│   │   │   ├── geography.html
│   │   │   ├── goals.html
│   │   │   ├── includes
│   │   │   │   ├── filter_bar.html
│   │   │   │   └── pagination.html
│   │   │   ├── log_detail.html
│   │   │   ├── login_activity.html
│   │   │   ├── logs.html
│   │   │   ├── mfa_enroll.html
│   │   │   ├── notifications.html
│   │   │   ├── page_detail.html
│   │   │   ├── pages.html
│   │   │   ├── realtime.html
│   │   │   ├── releases.html
│   │   │   ├── reports.html
│   │   │   ├── rum.html
│   │   │   ├── security_admins.html
│   │   │   ├── security_authentication.html
│   │   │   ├── security.html
│   │   │   ├── security_overview.html
│   │   │   ├── segments.html
│   │   │   ├── server_cpu.html
│   │   │   ├── server_deployments.html
│   │   │   ├── server_disk.html
│   │   │   ├── server_memory.html
│   │   │   ├── server_network.html
│   │   │   ├── server_overview.html
│   │   │   ├── server_processes.html
│   │   │   ├── server_queues.html
│   │   │   ├── server_services.html
│   │   │   ├── server_slow_queries.html
│   │   │   ├── settings.html
│   │   │   ├── shared_dashboard.html
│   │   │   ├── share_links.html
│   │   │   ├── sites.html
│   │   │   ├── traffic.html
│   │   │   └── uptime.html
│   │   └── paxalia_auth
│   │       ├── access-denied.html
│   │       ├── device-register.html
│   │       ├── device-verify.html
│   │       ├── forgot-password.html
│   │       ├── login.html
│   │       ├── password_change_done.html
│   │       ├── password_change.html
│   │       ├── password_reset_complete.html
│   │       ├── password_reset_done.html
│   │       ├── password_reset_email.html
│   │       ├── password_reset_subject.html
│   │       ├── recovery-codes.html
│   │       ├── reset-password.html
│   │       ├── session-expired.html
│   │       ├── signup.html
│   │       ├── two-factor.html
│   │       └── two-factor-setup.html
│   ├── templatetags
│   │   ├── analytics_tags.py
│   │   └── __init__.py
│   ├── test_admin_center.py
│   ├── test_live_logging_fix26.py
│   ├── test_logging.py
│   ├── test_security_auth.py
│   ├── test_security_cleanup_fix22.py
│   ├── test_security_ux_fix21.py
│   ├── tests.py
│   ├── uptime.py
│   ├── urls.py
│   ├── views
│   │   ├── about.py
│   │   ├── admin_overview.py
│   │   ├── admin_security.py
│   │   ├── annotations.py
│   │   ├── api_docs.py
│   │   ├── api_keys.py
│   │   ├── api.py
│   │   ├── auth.py
│   │   ├── backup.py
│   │   ├── billing.py
│   │   ├── bots.py
│   │   ├── broken_links.py
│   │   ├── campaigns.py
│   │   ├── chat_ops.py
│   │   ├── cohorts.py
│   │   ├── compliance.py
│   │   ├── csp_reports.py
│   │   ├── dashboard.py
│   │   ├── data_import.py
│   │   ├── dependencies.py
│   │   ├── events.py
│   │   ├── export.py
│   │   ├── geography.py
│   │   ├── goals.py
│   │   ├── __init__.py
│   │   ├── login_activity.py
│   │   ├── logs.py
│   │   ├── mfa.py
│   │   ├── notifications.py
│   │   ├── page_detail.py
│   │   ├── pages.py
│   │   ├── paxalia_api.py
│   │   ├── realtime.py
│   │   ├── releases.py
│   │   ├── reports.py
│   │   ├── rum.py
│   │   ├── security.py
│   │   ├── segments.py
│   │   ├── server.py
│   │   ├── settings.py
│   │   ├── share_links.py
│   │   ├── sites.py
│   │   ├── traffic.py
│   │   ├── uploads.py
│   │   ├── uptime.py
│   │   └── utils.py
│   └── webauthn_services.py
├── LICENSE
├── MANIFEST.in
├── pyproject.toml
├── README.md
├── setup.cfg
└── setup.py

The .mmdb GeoIP database is intentionally excluded from Git because of its size.

Contributing

Contributions are welcome.

The goal is to preserve Paxalia's existing architecture rather than accumulating independent feature-specific systems.

Development setup

git clone https://github.com/paxalia/paxalia-dashboard.git
cd paxalia-dashboard
python -m venv .venv
source .venv/bin/activate
pip install -e .

Then run the appropriate checks.

Baseline checks

python manage.py check
python manage.py paxalia_admin_test
python manage.py paxalia_logs_test --keep
python manage.py paxalia_dashboard_test --keep --no-ui

Focused Admin tests:

python manage.py test paxalia.test_admin_center -v 2

When working on logging:

python manage.py test paxalia.test_logging -v 2
python manage.py paxalia_logs_test --keep

When working on package functionality, also run:

python manage.py paxalia_package_validate path/to/test-package.paxalia
python manage.py paxalia_package_inspect path/to/test-package.paxalia

Diagnostic expectations

Do not claim a subsystem is healthy merely because a single page loads.

When a change touches Admin, verify:

  • registry discovery
  • permissions
  • model browsing
  • CRUD
  • relationships
  • inline support
  • package operations
  • localization
  • diagnostics

When a change touches logging, verify:

  • stdlib capture
  • direct paxalia.log()
  • request context
  • request-less events
  • exception persistence
  • redaction
  • grouping/fingerprints
  • dashboard visibility
  • retention/pruning
  • non-fatal failure behavior

Developer conventions

Paxalia uses:

  • Django-native patterns
  • token-driven CSS
  • reusable components
  • external JavaScript modules
  • defensive progressive enhancement
  • explicit security boundaries
  • generic configuration instead of host-model assumptions

Do not introduce an external UI framework merely to build an Admin page.

Do not move host-specific business logic into Paxalia.

Do not silently swallow operational failures merely to keep the UI looking successful.

Commit message format

Use Conventional Commit style:

type(scope): short summary

Common types:

feat(scope): ...
fix(scope): ...
refactor(scope): ...
style(scope): ...
docs(scope): ...
chore(scope): ...
perf(scope): ...
polish(scope): ...
test(scope): ...

For substantial changes, use a structured body:

feat(admin): improve generic model discovery

Scope:
- paxalia/admin_center/registry.py
- paxalia/templates/paxalia/admin/models.html
- paxalia/static/paxalia/scripts/admin-center.js

Changes:
- Added searchable application grouping
- Preserved Django ModelAdmin registration semantics
- Improved responsive presentation

Behavior:
- Administrators can locate models without scanning the entire registry

Impact:
- Large host projects remain easier to administer

Branching

A typical repository policy is:

main
feat/<name>
feat/<scope>/<name>
fix/<issue>
hotfix/<issue>
refactor/<name>
docs/<description>

Keep changes focused.

Avoid mixing an unrelated backend migration, dashboard redesign, and Admin change into one commit.

Ideas for contribution

The previous roadmap contained several items that are now implemented. The remaining ideas should therefore focus on capabilities that genuinely extend the current platform.

Feature Description Effort
City bubbles on the world map Add a richer country-to-city visualization on the geography surface Medium
Session replay / user journey Show a controlled sequence of anonymous session events without introducing fingerprinting Large
Custom dashboards Let administrators assemble selected cards/charts into personalized dashboard views Large
Behavior flow diagram Visualize supported page/event transitions Large
Additional languages Add complete translation catalogs for more locales Small
Section-specific theme preference Allow selected dashboard sections to use controlled presentation modes Medium
Admin dashboard widgets Surface selected analytics indicators alongside the generic Admin workspace Medium
Advanced retention/cohort exploration Add deeper cohort comparisons and retention views Medium
More alert policies Add configurable thresholds for selected operational/security conditions Medium
A/B testing integration Add first-party experiment measurement while keeping the data model explicit Large
Anonymous heatmap tooling Capture privacy-safe click-density data without browser fingerprinting Large
Expanded export formats Add carefully scoped machine-oriented logical package profiles Medium
Package dependency planner Show explicit dependency ordering before larger package imports Medium
Admin saved views Allow administrators to save safe model list/filter configurations Medium
Admin bulk workflow queue Move very large administrative operations into an explicit queued workflow Large
Plugin / extension system Allow controlled registration of additional dashboard sections and Admin capabilities Large
Local AI incident summaries Generate optional summaries from sanitized log context without sending raw logs to a hosted AI provider Large

New contributions should preserve Paxalia's central principles:

privacy-first
self-hosted
Django-native
security-aware
generic
auditable
maintainable

License

This project is licensed under the Apache License 2.0.

See LICENSE for the complete license text.

In practical terms, the Apache 2.0 license permits:

  • use
  • reproduction
  • modification
  • distribution
  • commercial use
  • derivative works

subject to the license conditions.

Credits

Built by Parsa Zaydany and published under the Paxalia brand.

The Story

Paxalia was built around a simple idea:

software should help people work with time, information, and collaboration without requiring every piece of their operational data to leave their own environment.

The dashboard reflects the same philosophy.

Instead of depending on a third-party analytics collector, it keeps application analytics and operational telemetry inside the Django project that owns the data.

About Paxalia

Paxalia is a workspace, timer, planner, and team-tools platform covering areas such as:

  • focused time tracking
  • notes
  • goals
  • an infinite canvas/board
  • Life OS workflows
  • live shareable pages
  • events and alarms
  • team communication

The Paxalia Dashboard is the open-source Paxalia project focused on Django applications and is part of the same ecosystem.

Support

If Paxalia helps your project, useful forms of support include:

  • starring the repository
  • sharing it with the Django community
  • contributing a language
  • contributing tests
  • contributing documentation
  • contributing a feature
  • supporting Paxalia through the project's official support/donation channels

Thank you for using paxalia-dashboard.

Future Security Setup & Bootstrap Tooling

Planned / not implemented in the current release.

This section documents a future contribution direction only. None of the commands below are available from the current package. Do not copy them into deployment automation expecting them to exist today.

The long-term goal is to provide an interactive Paxalia project-setup layer that can diagnose a Django project, preview proposed security/configuration changes, create backups, and then apply only changes that the administrator explicitly approves.

Future paxalia_check

A future command may provide a single read-only project health entry point:

python manage.py paxalia_check

The intended scope includes Django deployment checks, Paxalia security checks, authentication checks, configuration checks, logging checks, and Admin checks.

Future paxalia_setup

A future interactive setup command may inspect the host project and show a preview before making changes:

python manage.py paxalia_setup

The future workflow could inspect the project, preview proposed changes, create backups, configure Paxalia, configure security, configure logging, and configure authentication while preserving existing project behavior.

Future security setup

A future security-focused mode could be exposed as:

python manage.py paxalia_setup security
python manage.py paxalia_setup security --apply

A future implementation should first inspect the project safely and present a deterministic preview. Depending on the project, it could eventually:

  • detect existing security/authentication packages
  • propose only compatible dependencies
  • back up files before mutation
  • update .env safely where the project uses environment-based settings
  • update .env.example and .gitignore when appropriate
  • configure security middleware
  • configure Paxalia logging
  • configure administrator authentication and security
  • run Django/Paxalia validation after applying changes

The future tooling must preserve existing settings instead of blindly rewriting arbitrary settings.py files.

Future production security setup

A future production-oriented mode could be exposed as:

python manage.py paxalia_setup security --production --apply

This would still need to preview its intended changes, create backups, detect conflicts, and stop rather than silently overwrite project-specific configuration. Production mode should maximize safe automation, not remove administrator control.

Explicitly outside the current release

The current package does not automatically:

  • migrate settings.py secrets into .env
  • rewrite .env files
  • modify requirements.txt, pyproject.toml, Poetry configuration, or other dependency manifests
  • rewrite arbitrary Django settings files
  • bootstrap a deployment automatically
  • provide the future paxalia_check command
  • provide the future paxalia_setup command

For the current release, Security Overview is intentionally diagnostic and read-only: it tells administrators what is active, what is missing, and what requires attention. Future setup tooling can build on those diagnostics later without changing the completed security architecture.

Created with love by the Paxalia team for the world — because detail matters.

Detail is in the layers you may not notice first: thoughtful security boundaries, password + 2FA + authorized-device authentication, rate limits, CSRF protection, isolated administrator sessions, a private dashboard path, twelve token-driven themes, a clean Django-native structure, careful data portability, persistent observability, and the small decisions that make the whole system feel considered.

Paxalia Dashboard is built around the belief that the details are part of the product.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for paxalia from gravatar.com paxalia

Credits

Author: Paxalia

License

Apache Software License (Apache-2.0)

Requires

Python >=3.10

Tags

django analytics privacy self-hosted dashboard geoip world-map chartjs

Classifiers

Report project as malware

Release files for paxalia-dashboard 4.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for paxalia-dashboard 4.0.0
File Size Uploaded
paxalia_dashboard-4.0.0.tar.gz 799.9 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for paxalia-dashboard 4.0.0
File Interpreter ABI Platform
paxalia_dashboard-4.0.0-py3-none-any.whl 880.9 kB Python 3 none any Details

Total release size: 1.7 MB

Release files / paxalia_dashboard-4.0.0.tar.gz

Download URL paxalia_dashboard-4.0.0.tar.gz
Size 799.9 kB
Tags Source
SHA-256 checksum
How to use checksums 		eb8d4475ba4e3e19df69e5d06248845b8fdf289177f4e0a127d1e00d036c06bb
BLAKE2b-256 checksum
How to use checksums 		a96149b8e04f81945090ccb3259e0cb8c859bd18a4c5ef9ca68897d24e3a9151
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / paxalia_dashboard-4.0.0-py3-none-any.whl

Download URL paxalia_dashboard-4.0.0-py3-none-any.whl
Size 880.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums 		4d5a197d2f4de146def3a994a9c07c0b4d4da82a0c34a1cf27b96c2fde43689b
BLAKE2b-256 checksum
How to use checksums 		b06789a2e101ec6f1bdb52a58e42f4a7af12ccbe9cd32f915fdc1e29046b7556
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		No
Uploaded via twine/7.0.0 CPython/3.12.3

Release history Release notifications | RSS feed

This release

4.0.0 This release

2 release files

3.0.0

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page