Skip to content

Architecture

Consumer requirements 3.1 and ADR 0008 are the current product authority; the personal-agent 2.1 scope still applies where it does not conflict with 3.1. The independent personal application has registered sessions, private state, owner management and dedicated background workers. The Astro website remains static and does not hold private state. Personal interfaces use the same governed core as agent interfaces. The product scope says what has shipped.

Casdoor is the external OAuth/OIDC authorization server. Argus API/MCP are resource servers; a separate trusted identity component exchanges upstream codes and maintains encrypted sessions. OAuth API and MCP requests use separate audiences, one configured shared institution, and stable caller IDs derived from issuer plus subject. OAuth subjects are not machine accounts. See MCP for how an AI app signs in.

Argus separates machine access adapters from governed business logic. CLI + Skill, MCP, and REST translate requests, authenticate the caller, and delegate to the same core services. They do not query databases, object storage, or data vendors directly.

AI agent
  -> CLI + Skill | MCP | REST
  -> machine authentication
  -> CommandLineToolService
  -> CoreServiceBoundary
       1. write-ahead audit start
       2. tenant isolation
       3. permission check
       4. core operation
       5. license check
       6. schema, evidence, and output-origin validation
       7. terminal audit record
  -> shared structured result envelope

Argus does not generate an investment judgment. Investment wording and intended independent analysis do not block otherwise permitted fact access. A client AI agent may use lawfully accessible results for unrestricted independent reasoning and downstream output. Data-access controls such as authentication, tenant isolation, permissions, licenses, restricted fields, rate limits, and audit remain mandatory.

Consumer MCP facade

src/argus/consumer registers 20 intent tools on the OAuth MCP server only (requirements 3.1, section 6.2). Each tool calls the existing governed and personal tools, and every child call is still authorized and audited on its own. Answers use the consumer-result-v1 envelope. Consumer reads return only sources that config/consumer_rights.yaml marks visible. See Consumer tools.

One consumer tool call builds its governed runtime once (src/argus/core/tool_call_governance.py): the authentication gateway, the rate limiter, the licence and output-policy services, the access guard and the boundary. Only these objects are shared. Every child still counts against the rate limit of its own tool, has the access guard read the account's current state from the database before and after its work, and has its permission, licence and output policy evaluated. Access revoked while a tool call runs is therefore refused at the next child.

The children's audit records and usage rows are kept in memory while the tool call runs and are written in one transaction when it ends, before the answer is returned. If that write fails, the answer is withheld and the call reports a temporary failure. A process that stops in the middle of a tool call leaves no audit record for it and has delivered nothing. Calls outside a consumer tool call (CLI, REST, the machine MCP and the personal tools) write the start record before the operation and the final record after it, as before.

Runtime services

Service Responsibility Public exposure
api REST, onboarding, skills, health, metrics API hostname through TLS proxy
mcp-oauth OAuth MCP: the consumer tools only; registry tools are neither listed nor callable MCP hostname /mcp through TLS proxy
mcp-machine Machine-authenticated MCP at /mcp-machine None; the edge answers 404
worker Governed Celery task execution None
beat Scheduled retention and vector-index maintenance None
PostgreSQL + pgvector Persistent domain data, audit, task, and vector records None
Redis Rate limiting, Celery broker/result coordination, locks None
Object storage Filing source objects and export artifacts None
Static website Documentation, search, onboarding, aggregate usage snapshot Website hostname only; no tool execution
personal-app Private owner pages and account management Separate registered application origin; private no-store responses
Identity/session component PKCE code exchange, encrypted upstream credentials, registered Argus sessions Fixed session protocol and trusted service access; separate identity database and secrets
Personal notification/export/deletion workers Durable, fenced jobs in separate queues None

Core domains

The src/argus/core package contains the business boundary and services for company/security master data, filings, evidence mapping, events, corporate actions, market data, neutral metrics, point-in-time snapshots, data quality, licenses, trust, async tasks, permissions, and audit. Public Pydantic contracts live in src/argus/schemas; persistence models and repositories live below src/argus/models and src/argus/db.

Data ingestion path

Connectors fetch raw source records under a versioned registry definition. The service validates provider, secret, license, allowed use, rate limit, parser version, and field-mapping version before synchronization. Normalizers convert vendor-specific payloads into neutral domain records and source evidence. Filing content can additionally flow through ingestion, parsing, fragmenting, fact extraction, evidence mapping, and optional vector indexing.

Consistency invariants

  • Equivalent requests through CLI, MCP, and REST preserve fact, evidence, time, quality, license, restriction, and audit semantics.
  • Public schema models reject undeclared fields.
  • A fact cannot cite an evidence id absent from its package.
  • Historical reads exclude facts whose known_time is later than as_of.
  • Credentials, secrets, and raw sensitive values are redacted from audit output.
  • Connector schema, credential, normalization, persistence, and audit validation remain fail-closed. Generic ordinary-read license enforcement defaults off; additional source uses, including export and redistribution, retain their always-on current-rights checks.
  • The static website remains independent of the API/MCP runtime lifecycle.

The runtime services table above shows which services the public edge exposes; everything else stays on the internal network.

P1 contract kernel and generated interfaces

argus.contracts contains the shared closed envelope and entity, security, ETF, market, option, filing, and macro payload families. argus.core.tool_registry selects the input version, output version, payload family, capability, time semantics, provider coverage, replacement, and exactly three public bindings for every tool. scripts/generate_interfaces.py materializes those declarations into checked-in MCP, REST, Skill, and documentation artifacts; runtime CLI remote routing and MCP contract metadata consume the generated authority directly. The CLI binding table has no runtime reader, so the generator only builds it in memory (cli_bindings()) for tests.

The P1 golden contract and live adapter parity test are release gates. Generated files must pass scripts/generate_interfaces.py --check, and all request/payload object schemas reject unknown fields.

P3 normalized market domains

Options data here, the P4 screener and export, and the P5 feature DAG are advanced capabilities. Under requirements 3.1 they are hidden from consumer discovery and retire in phase 5; see the product scope.

UsEquityEtfOptionDataService is a read-only domain boundary for US security master/session data, bitemporal ETF snapshots, market observations and corporate action adjustments, and option contract/chain data. Persistence is normalized by revision 0032_us_equity_etf_options. ETF visibility requires effective, publication, and known-time eligibility; adjustments link to actions and a versioned policy. Provider coverage, delay, missing fields, and license status are part of each payload. Provider-supplied greeks retain model and input metadata and never acquire strategy or transaction semantics.

P4 point-in-time query and export

PitCatalogService provides the shared Calendar, Instrument, Feature, and Dataset point-in-time abstractions. Its closed screener DSL enforces field/type/provider/ license/scan limits and stable cursor pagination. The same selected factual rows feed deterministic Arrow IPC and Parquet partitions whose manifest records schema, content, partition, time, source, license, adjustment, cache, and dataset identity. Exports contain no execution engine or performance semantics.

P5 deterministic metrics and feature DAG

FeatureDagService is the only derived-value execution path for new interfaces. It resolves immutable formula id/version pairs from MetricCatalog, verifies PIT eligibility and evidence for every fact, validates an acyclic bounded graph, and executes fixed Decimal operators in a stable topological order. Canonical requests bind cache identity; derived records retain transitive fact, evidence, provider, as-of, known-at, and formula-version lineage. Multi-source comparison retains all values and pairwise differences and has no best-source selection field. Public outputs are structured values and metadata only.

Personal core foundations

The independent personal service uses existing OAuth subjects, shared governance and new additive persistence. Personal state defines stable ownership, lifecycle, preferences and denial retention. Domain consent intersects each trusted client's verified scopes with current explicit owner grants. Confirmation binds server-resolved effects and versions to owner approval and recent verification for account operations. Registered sessions, CLI/REST/MCP personal adapters, owner pages, revocation, private workflows and six-language application flows (ADR 0008) are implemented on these foundations. Sensitive management stays outside ordinary Agent tools. See the session protocol and personal tool contracts. Private results use per-tool personal-result-v1 schemas; financial children retain their existing contracts and evidence. Implementation and delivery do not imply that every source, client or production scenario passed verification.