Application Modules Reference

This is the reference for app/modules/ — the six domain packages that hold the platform's business logic. Each entry gives the module's responsibility, its entry points (routes, services, workers), the invariants its code enforces, and pointers to its tables and topic documents. For the surrounding architecture (blueprints, services, repositories) see ARCHITECTURE.md; for per-route permissions see API_PERMISSION_MATRIX.md.

Table references point into DATABASE_SCHEMA.md by domain group. Its domain map covers all 103 tables; the Alembic migration under migrations/versions/ that created a table remains the canonical DDL.

Module	Responsibility	Primary routes
analytics	Usage analytics, ROI, cost optimization	routes/analytics.py, routes/roi.py
compliance	Compliance reports, data retention	routes/compliance.py
governance	Audit logging, content filter, quotas, alerts	routes/governance.py, alerts.py, quota.py
policy	Pluggable policy & approval engine	routes/policy.py
sso	OAuth2 / OIDC / SAML single sign-on	routes/sso.py
workspace	Sessions, remote workspaces, autonomous development	routes/workspace.py, remote.py, autonomous.py

analytics

Enterprise usage analytics: trends and anomaly detection, ROI calculation, and cost-optimization suggestions.

Entry points

• Routes: app/routes/analytics.py, app/routes/roi.py

Key files: usage_analytics.py, cost_optimizer.py, roi_calculator.py, efficiency_registry.py, efficiency_thresholds.py, task_type_inferencer.py

Invariants & design constraints

• Efficiency algorithms are versioned through efficiency_registry.py: register → A/B gradual rollout → full release → deprecate → remove (6+ months later); rollback is a version switch, not a code change.
• Every threshold in efficiency_thresholds.py carries a documented source (EXPERIENCE / HEURISTIC / TO_BE_VALIDATED) — no unexplained magic numbers.
• Thresholds are task-type aware; task_type_inferencer.py classifies tasks by tool_name pattern (general / code generation / document analysis / conversation).
• Forecasting (Issue #3244) uses continuous calendar days, excludes the incomplete current day, and returns history-window metadata so consumers can verify the window.

Tables: Statistics group — daily_stats, hourly_stats, daily_usage, usage_summary, session_stats (materialized view).

Tests: tests/unit/test_usage_analytics.py, test_cost_optimizer.py, test_efficiency_registry.py, test_roi_cost_consistency.py.

See also: TOKEN_ACCOUNTING.md explains where these usage numbers come from.

compliance

Compliance reporting and data retention: analyzes the audit trail, generates regulatory reports, and enforces retention policies.

Entry points

• Routes: app/routes/compliance.py

Key files: report.py, audit.py, retention.py

Invariants & design constraints

• Compliance is a consumer of governance's audit trail: audit.py analyzes rows written by app/modules/governance/audit_logger.py. The writer lives in governance; only the analyzer lives here.
• retention.py is mapping-driven: every data_type maps to a (table, time_column) pair; deletes are counted, support dry-run, and every run is recorded in retention_history.
• report.py reads existing tables (usage, audit, quota) rather than owning domain tables of its own; reports target enterprise/regulatory shapes (SOX/GDPR/HIPAA-style sections).

Tables: reads audit_logs (Governance & Compliance); writes retention_history (Sync & Retention Snapshots).

Tests: tests/unit/test_retention.py, test_audit_analyzer_2750.py, test_report_csv_excel_nested_fields.py.

governance

The enterprise governance runtime: audit logging, content filtering (PII detection), quota management, and alerting/notification.

Entry points

• Routes: app/routes/governance.py, alerts.py, quota.py, admin.py, auth.py, plus most admin/config routes (ai_agent_settings.py, feishu_config.py, smtp_config.py, notification_integrations.py, tool_accounts.py, …)
• Background: app/services/alert_compensation_worker.py, deregister_compensation_worker.py, pending_revoke_cleanup.py, quota_enforcement_scheduler.py

Key files: audit_logger.py, content_filter.py + content_filter_singleton.py, quota_manager.py, alert_notifier.py, alert_transaction_manager.py, alert_state_synchronizer.py

Invariants & design constraints

• In audit logs, resource_id is ALWAYS a real entity primary key (user_id, rule_id, alert_id, machine_id, …) or NULL — never a synthesized token prefix or date hash. Entity-less operations (login/logout/config singletons) correctly leave it NULL.
• details is persisted as JSON TEXT and parsed at a single point (AuditLog._parse_details via from_dict) — do not add audit_logs queries that bypass query()/from_dict.
• ContentFilter is a process-wide singleton (Issue #2768) so a rule CRUD refreshes the one cached instance all modules share; in multi-process deployments each process still has its own singleton (cross-process sync is a known follow-up).
• Quota alerts dual-write to both quota_alerts and alerts: alert_transaction_manager.py wraps the pair in a transaction with retry (up to 3) plus a failure-compensation queue; alert_state_synchronizer.py re-consistifies the two tables on acknowledge/delete/cleanup.
• alert_notifier.py fans alerts out over WebSocket push, email, and webhook.

Tables: Governance & Compliance (audit_logs, content_filter_rules) and Alerts & Quotas (alerts, quota_usage, quota_alerts, notification_preferences).

Tests: tests/unit/test_audit_logger.py, test_content_filter.py, test_e2e_governance.py.

policy

A pluggable, self-contained policy engine (MVP) for remote-agent actions. It owns the durable decision lifecycle; the CLI permission request is merely the input event that starts it.

Entry points

• Routes: app/routes/policy.py (admin CRUD for rules)
• Integration sites elsewhere are 1–2-line guarded evaluate() calls at permission/approval points

Key files: evaluator.py, models.py, repo.py, cache.py, fingerprint.py

Invariants & design constraints

• Feature-flagged: policy.enabled (60s TTL) in ~/.open-ace/config.json. When off, get_evaluator() returns a NullPolicyEvaluator and the system behaves exactly as before (real-time manual approval) — every call site can call evaluate() unconditionally.
• Fail-closed: evaluate() NEVER raises. On internal error it returns require_human for tool targets and deny for model/provider selection, so a broken rule store can neither auto-allow nor silently select a denied model.
• Deterministic specificity ranking: machine > project > user > team > tenant, then explicit priority, then created_at; first match wins. No match → require_human (tools) / allow (model selection).
• Rules are immutable versioned snapshots: an edit inserts a new row (version + 1, is_current = true) and every decision pins (rule_id, rule_version), so a later edit can never retroactively change a past decision.
• Fingerprints fold only surface forms via versioned normalization profiles (generic:v1, bash-command:v1, file-path:v1) — never make a path or command more permissive.
• Persistence: the decision INSERT and the atomic consume_decision UPDATE run synchronously in repo.py (never via the async run-timeline writer); decisions are soft-linked to agent_approvals by request_id (no hard FK — the input event is persisted asynchronously).

Tables: policy_rules / policy_decisions — listed in the "Autonomous Development" group of DATABASE_SCHEMA.md; canonical DDL in migrations/versions/20260626_005_add_policy_tables.py. The evaluation hot path is served from a 60s TTL rule cache (cache.py) invalidated by admin CRUD.

Tests: tests/unit/test_policy_evaluator.py, test_policy_fingerprint.py, test_policy_repo.py, test_policy_integration.py.

sso

Single sign-on for enterprise authentication: OAuth2, OIDC, and SAML 2.0 behind one provider abstraction.

Entry points

• Routes: app/routes/sso.py
• Org-sync jobs: app/services/feishu_org_sync.py, dingtalk_org_sync.py; also app/scheduler_worker.py

Key files: manager.py, provider.py, oauth2.py, oidc.py, saml.py, secret_holder.py, exceptions.py

Invariants & design constraints

• One SSOProvider contract covers all three protocols; OIDCProvider extends the OAuth2 flow with ID-token verification; SAMLProvider implements SP metadata / AuthnRequest / ACS with XML signature verification.
• Provider secrets (client_secret, …) live in SecretHolder, an in-memory holder that prevents accidental logging or serialization.
• SSOManager owns the provider lifecycle and authentication sessions; org-sync services go through it rather than touching providers directly.

Tables: SSO group — sso_providers, sso_identities, sso_sessions.

Tests: tests/unit/test_sso_manager_security.py, test_sso_redirect_whitelist_3224.py, test_sso_auto_provision_2893.py.

See also: SSO_CONFIG.md for provider configuration.

workspace

Everything around agent sessions — the "用" (Use) plane of the platform: session persistence, remote workspaces, browser-access proxies, usage recording, and the autonomous-development stack. It is by far the largest module; navigate it as a set of subdomains.

Sub-structure guide

• Session core — session_manager.py (persistence/recovery), state_sync.py (real-time sync), prompt_library.py, collaboration.py, tool_connector.py, tenant_config_cache.py.
• Remote workspace — remote_agent_manager.py (agent WebSocket connections, heartbeat, command dispatch), remote_session_manager.py (session lifecycle, message forwarding), session_access.py, agent_token.py, api_key_proxy.py + api_key_router.py, llm_proxy_handler.py, and the usage pipeline usage_parser.py → usage_evidence.py → usage_dedup.py → usage_sink.py (plus usage_diagnostics.py).
• Browser-access proxies — VSCode (vscode_proxy.py / vscode_store.py / vscode_ws_bridge.py) and terminal (terminal_store.py / terminal_ws_bridge.py / terminal_relay_store.py), with relay_distributed_store.py providing Redis-backed HA state.
• run_timeline/ — persisted provenance for remote sessions: one durable agent_runs record per session, an append-only agent_run_events stream, and durable agent_approvals.
• model_gateway/ — optional LiteLLM-compatible routing of LLM proxy traffic; see MODEL_GATEWAY.md.
• autonomous/ — autonomous-development orchestration: orchestrator.py, phases/ (development, PR review, acceptance verification, merge), git_workspace.py, github_ops.py, and the evidence subsystem; autonomous/sandbox/ holds the execution-isolation backends. See AUTONOMOUS_DEVELOPMENT.md and SANDBOX_BACKENDS.md.

Entry points

• Routes: workspace.py, remote.py, autonomous.py, model_gateway.py, run_timeline.py, api_keys.py, usage.py, tenant.py, workspace_isolation.py
• Services: workspace_service.py, webui_manager.py, webui_sandbox.py, autonomous_scheduler.py, data_fetch_scheduler.py, insights_service.py, workspace_isolation_contract.py
• WebSocket plumbing outside the module: app/remote_ws_handler.py, app/terminal_ws_middleware.py

Invariants & design constraints

• API keys never leave the server: api_key_proxy.py stores them encrypted and hands remote agents short-lived proxy tokens, exchanged for real keys only by the server's LLM proxy endpoint.
• Registration tokens are one-time-use (machine enrollment); agent tokens are long-lived Bearer credentials for heartbeat/message endpoints (agent_token.py).
• Session authorization is shared code: session_access.py centralizes the owner / system-admin / machine-admin check (and remote-user loading) so the remote and run-timeline blueprints cannot drift apart.
• Usage recording is provider-neutral and deduplicated at request level before reaching the unified sink (Issue #2184).
• The run timeline is append-only and self-contained, so the feature can be removed or re-implemented behind an external API with minimal scarring.
• The model gateway preserves quota, usage recording, attribution, and direct-provider behavior; there is a single integration seam in llm_proxy_handler.handle_llm_proxy_request (Null/real planner pair with an is_noop short-circuit).
• Relay state is tiered: terminal metadata is process-local with TTL cleanup, while cross-pod HA comes from the Redis-backed relay_distributed_store.py (circuit breaker, 300s TTL, graceful degradation to in-memory when Redis is down).
• Sandbox callers depend on the autonomous/sandbox/ package contract surface, never on the internal module layout.

Tables: Messages & Sessions (agent_sessions, session_messages), Workspace & Projects (prompt_templates), Remote Workspace (remote_machines, machine_assignments, api_key_store, proxy_token_jtis), Collaboration, Sync & Retention Snapshots. Run-timeline and gateway tables (agent_runs, agent_run_events, agent_approvals, model_gateway_config) are listed in the "Autonomous Development" / "Other Domains" groups of DATABASE_SCHEMA.md.

Tests: tests/unit/test_api_key_proxy_*.py, tests/unit/test_api_key_router.py, tests/autonomous/, tests/integration/routes/.

See also: WORKSPACE_ISOLATION_CAPABILITIES.md, REMOTE_WORKSPACE.md