Filesystem Organization

This document describes the specific filesystem organization for the project, showing how the standard organizational patterns are implemented for this project’s configuration. For the underlying principles and rationale behind these patterns, see the common architecture documentation.

Project Structure

Root Directory Organization

The project implements the standard filesystem organization:

python-ictr/
├── LICENSE.txt              # Project license
├── README.rst               # Project overview and quick start
├── pyproject.toml           # Python packaging and tool configuration
├── documentation/           # Sphinx documentation source
├── sources/                 # All source code
├── tests/                   # Test suites
└── .auxiliary/              # Development workspace

Source Code Organization

Package Structure

The main Python package follows the standard sources/ directory pattern:

sources/
└── ictr/                        # Main Python package
    ├── __/                      # Centralized import hub
    │   ├── __init__.py          # Re-exports core utilities
    │   ├── imports.py           # External library imports
    │   ├── miscellany.py        # Utility functions
    │   ├── nomina.py            # Naming constants
    │   └── validators.py        # Validation decorators
    ├── __init__.py              # Package entry point
    ├── py.typed                 # Type checking marker
    ├── exceptions.py            # Exception hierarchy
    ├── configuration.py         # Configuration dataclasses
    ├── dispatchers.py           # Dispatcher entry points
    ├── reporters.py             # Reporter coordination
    ├── textualizers.py          # Compositor and linearizer protocols
    ├── printers.py              # Printer protocols
    ├── flavors.py               # Flavor specifications
    ├── records.py               # Message records
    ├── inspection.py            # Stack frame inspection
    ├── standard/                # Standard recipes
    │   ├── __.py                # Subpackage imports (inherits from parent)
    │   ├── __init__.py          # Subpackage entry point
    │   ├── core.py              # Core configuration dataclasses
    │   ├── flavors.py           # Standard flavor definitions
    │   ├── introducers.py       # Introduction formatters
    │   ├── linearizers.py       # Content-to-lines converters
    │   ├── compositors.py       # Standard compositor implementations
    │   └── printers.py          # Standard printer implementations
    └── _typedecls/              # Vendored type declarations
        └── wcwidth/             # Terminal width calculation types

All package modules use the standard __ import pattern as documented in the common architecture guide. The standard subpackage implements the cascading import pattern, inheriting parent imports via from ..__ import * while adding specialized dependencies.

Component Integration

Exception Organization

Package-wide exceptions are centralized in sources/ictr/exceptions.py following the standard hierarchy patterns documented in the common practices guide.

Architecture Evolution

This filesystem organization provides a foundation that architect agents can evolve as the project grows. For questions about organizational principles, subpackage patterns, or testing strategies, refer to the comprehensive common documentation:

• Architecture Patterns

• Development Practices

• Test Development Guidelines