# Repository architecture

## Top-level folders

| Folder        | Responsibility                                                                                                                    |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------|
| `logicytics/` | Public package, CLI, and the internal engine modules for contracts, configuration, discovery, planning, runtime, logging, manifests, packaging, and platform adapters |
| `core/`       | Shipped read-only collector implementations grouped by specialty                                                                  |
| `plugins/`    | Opt-in user-owned `PluginCollector` implementations                                                                               |
| `tests/`      | Unit, contract, resilience, security, and Windows integration tests                                                               |
| `docs/`       | This user, operator, and developer manual                                                                                         |
| `output/`     | Local run output; do not commit evidence                                                                                          |
| `.github/`    | Contribution templates, security automation, and documentation publishing workflow                                                |

## Engine modules

- `module/contracts.py` defines enums, metadata, request, context, artifact, result, and collector interfaces.
- `configuration.py` loads and validates `logicytics.yaml`.
- `discovery.py` finds candidates, performs static checks, probes metadata, and manages the disposable validation cache.
- `planner.py` resolves profiles, selectors, dependencies, capabilities, ordering, and run fingerprints.
- `runtime.py` owns worker processes, quotas, cancellation, retry rules, progress, and terminal statuses.
- `artifacts.py` is the workspace-bound artifact writer.
- `manifest.py` writes the durable run record.
- `packaging.py` builds and verifies ZIP packages and hash sidecars.
- `api.py` exposes planning, collection, run queries, and bounded artifact reads.
- `module/platform_adapters.py` owns the injectable host-process and Windows API boundaries.
- `cli/terminal.py` manages console lifecycle and `cli/virtual_environment.py` validates the supported interpreter environment.
- `cli/commands.py` maps command-line arguments to the public engine operations.

## Boundary rules

Collectors may depend on contracts and approved platform adapters. They should not reach into supervisor internals,
write outside their workspace, alter global configuration, or create unbounded output. The runtime owns cleanup and
process termination. The manifest is the source for later inspection; do not infer success from a console line alone.

## Core source layout

The core ID follows `core.<specialty>.<name>` and normally maps to `core/<specialty>/<name>.py`. A module contains one
collector class with a PascalCase name ending in `Collector`, a `metadata()` class method, lifecycle methods, and no
import-time collection. The catalog in [Core Collectors](CORE_COLLECTORS.md) is grouped by the live source tree.