Architecture
Understand the current Argus workspace boundaries and the flow from public sources to stored records, API queries, releases, and documentation.
The repository is organized around small packages with one direction of responsibility: source adapters create source items, the engine normalizes and classifies them, storage persists canonical records and revisions, and the app coordinates scheduled work and the API. Shared domain contracts keep those layers explicit.
Workspace boundaries
| Area | Current responsibility |
|---|---|
packages/contracts | Shared domain, source, storage, OCI, and management-wrapper contracts. |
packages/config | YAML schema, loading, reconciliation, and secret-reference sanitization. |
packages/source-x, packages/source-telegram, packages/source-web | Adapters and clients for the three public source families. |
packages/engine | Source-item ingestion, normalization, and classification. |
packages/storage-sqlite, packages/storage-postgres | Drizzle repository implementations and equivalent v2 schemas. |
packages/scheduler | Schedule derivation, job creation, backoff, and worker coordination. |
packages/intelligence | Optional OpenRouter summaries, query answers, capability discovery, and pointer-only multimodal content. |
apps/argus | Runtime composition, HTTP application, workers, and role selection. |
apps/cli and packages/deployment | Stable management CLI, onboarding, Compose rendering, doctor, repair, update, and external-integration boundaries. |
packages/release | Release manifests, signed installer and wrapper generation, and deterministic Agent Skill archives. |
apps/web | Next.js landing page, Fumadocs content, machine-readable routes, installer route, and Agent Skill distribution. |
Runtime flow
Configuration is loaded through @argus/config; secret values are resolved at
runtime rather than copied into the applied configuration. The scheduler turns
watches into leased jobs. A worker selects the relevant source adapter, passes
items through @argus/engine, and stores records, revisions, checkpoints, and
artifacts through the chosen repository. The API exposes
deterministic records with source links. Optional intelligence reads stored
records and writes a separate summary or answer artifact. Authenticated source
primitives proxy bounded FxEmbed and SearXNG reads without repository writes.
SQLite runs only in the combined all runtime role. PostgreSQL supports the
separate api, scheduler, worker, and processor roles. Keep this storage
constraint intact when changing runtime composition.
Change boundaries
Add a source by pairing an adapter package with its configuration schema, contracts, runtime registration, tests, and user documentation. Add a storage behavior to the contracts first, then implement and test it in both storage packages when it is portable. Management changes go through the CLI and deployment packages; do not make the site, skill, or prose an independent deployment implementation.
The web app is a separate public surface. It derives human docs, /llms.txt,
/llms-full.txt, and per-page Markdown from the same MDX source, while the
installer and Agent Skill routes consume the repository release and skill
packages.