feat(visitor-analytics): add module descriptor, permissions, and configuration gate #617

Context

AWCMS-Mini already has base modules for reporting, logging/audit, module management, tenant, identity/access, offline/LAN deployment, and online tenant-domain routing. Visitor analytics should be added as a new first-party module instead of overloading reporting or logging, because visitor telemetry has higher volume, different retention, and different privacy controls.

This issue starts the Visitor Analytics epic for human visitor statistics in both online and offline/LAN configurations.

Objective

Add the visitor_analytics module foundation with descriptor metadata, permissions, navigation, and a privacy-first configuration gate.

Scope

Add:

• src/modules/visitor-analytics/module.ts
• src/modules/visitor-analytics/README.md
• Registration in src/modules/index.ts
• Minimal docs references where needed

Module descriptor:

key: "visitor_analytics"
name: "Visitor Analytics"
type: "system"
status: "active"
dependencies: ["tenant_admin", "identity_access", "logging", "reporting"]

Permissions to add to the catalog/descriptor as appropriate:

• visitor_analytics.dashboard.read
• visitor_analytics.realtime.read
• visitor_analytics.sessions.read
• visitor_analytics.events.read
• visitor_analytics.raw_detail.read
• visitor_analytics.settings.read
• visitor_analytics.settings.update
• visitor_analytics.retention.purge

Navigation:

• /admin/analytics
• Required permission: visitor_analytics.dashboard.read

Configuration defaults:

VISITOR_ANALYTICS_ENABLED=true
VISITOR_ANALYTICS_MODE=basic
VISITOR_ANALYTICS_COLLECT_ADMIN=true
VISITOR_ANALYTICS_COLLECT_PUBLIC=true
VISITOR_ANALYTICS_COLLECT_API=false
VISITOR_ANALYTICS_DETAILED_ENABLED=false
VISITOR_ANALYTICS_RAW_IP_ENABLED=false
VISITOR_ANALYTICS_RAW_USER_AGENT_ENABLED=false
VISITOR_ANALYTICS_GEO_ENABLED=false
VISITOR_ANALYTICS_TRUST_PROXY=false
VISITOR_ANALYTICS_TRUST_CLOUDFLARE=false
VISITOR_ANALYTICS_ONLINE_WINDOW_SECONDS=300
VISITOR_ANALYTICS_EVENT_RETENTION_DAYS=90
VISITOR_ANALYTICS_RAW_DETAIL_RETENTION_DAYS=30
VISITOR_ANALYTICS_ROLLUP_RETENTION_DAYS=730
VISITOR_ANALYTICS_HASH_SALT=

Out of scope

• Database analytics tables.
• Middleware collector.
• Dashboard UI implementation.
• Online geolocation enrichment.
• Rollup/purge jobs.
• Third-party analytics integrations such as Google Analytics or Matomo.

Acceptance criteria

• visitor_analytics appears in the module registry.
• Module descriptor does not contain any secret, token, provider credential, or runtime-specific value.
• Module can be tracked by module management and can later be tenant-enabled/disabled according to existing module lifecycle rules.
• Permission catalog entries are added via migration or existing permission seed pattern.
• Navigation entry is available only to users with visitor_analytics.dashboard.read.
• Default configuration remains safe for development and offline/LAN deployments.
• VISITOR_ANALYTICS_MODE=basic is privacy-first: raw IP, raw user-agent, and geolocation are disabled by default.
• bun run config:validate passes with default offline/LAN configuration.
• bun run check passes.

Security and privacy notes

• Treat IP address, username/login identifier, user-agent, browser/device, and geolocation as personal or sensitive operational data.
• Default must not store raw IP or raw user-agent.
• Raw detail access must be separated from aggregate dashboard access through visitor_analytics.raw_detail.read.
• Do not make analytics dependent on any external provider.

Dependencies

None. This is the first issue in the Visitor Analytics epic.