# Project Architecture: AI-Enhanced CTF Toolchain

This document describes the current architecture, directory layout, core modules, and testing setup of the CTF Toolchain project.

---

## 1. Directory Structure

The project follows a standard modern Python layout (utilizing `src/` directory layout) and is managed via the `uv` toolchain.

```text
├── config.toml           # Mock/Default configuration for local testing
├── pyproject.toml        # Hatchling build configuration & project dependencies
├── uv.lock               # uv lockfile for exact dependency resolution
├── src/
│   └── ctf/
│       ├── __init__.py   # Module initializer
│       ├── main.py       # CLI Entry Point
│       ├── commands.py   # CLI Commands and action functions
│       ├── utils.py      # Core utility functions (file parsing, config, paths)
│       └── forensics.py  # Placeholder for future forensics analysis tools
└── tests/
    ├── env/              # Sandboxed, persistent test environment directories
    └── test_utils.py     # Unit/Integration tests for utility functions
```

---

## 2. Core Modules & Configuration

### A. Configuration & State ([config.toml](file:///home/venus/code/ctf/config.toml))
The toolchain requires configuration of directories and active challenges:
*   `Competition`: Keeps track of the current `producer`, `competition`, `category`, and `challenge`.
*   `Environment`: Declares the base directory (`ctf_dir`) where all CTF files are stored.

### B. Utilities ([utils.py](file:///home/venus/code/ctf/src/ctf/utils.py))
Provides helper functions for filesystem management and configuration parsing:
*   `load_config(path)`: Loads and parses configuration data from a TOML file.
*   `write_config(data, path)`: Serializes/updates a dictionary to a TOML file.
*   `active_categories(path)`: Iterates over a competition path to return all active categories.
*   `active_competitions(dir)`: Scans the base directory for active competitions, skipping designated helper directories (like `tools`).

### C. Commands ([commands.py](file:///home/venus/code/ctf/src/ctf/commands.py))
Houses the logic for each CLI command action:
*   `test()`: A simple hello-world tester.
*   `Set_Challenge(comp, chal, setDirectory)`: Sets the current active challenge/competition context. *(Note: Currently has a `NameError` due to reference to an undefined `state` object.)*

---

## 3. CLI Entry Point ([main.py](file:///home/venus/code/ctf/src/ctf/main.py))

*   Currently acts as a simple entry point calling `commands.test()`.
*   Uses `click` as the planned framework to build a sub-command CLI system (`ctf test`, `ctf set-challenge`, etc.).

---

## 4. Test Infrastructure

*   **Framework**: `pytest` (run via `uv run pytest`).
*   **Sandbox**: [tests/env](file:///home/venus/code/ctf/tests/env) acts as a persistent mock directory tree containing temporary competition directories (like `comp1`, `comp2`) to safely test category scanning and config loading/saving without touching actual user data.