Project structure

FalconSmith libraries follow a strict, explicit project structure designed for long-lived scientific and engineering software.

Canonical generated structure

The structure below is taken directly from a FalconSmith library immediately after successful generation and verification.

It represents the literal output of an inspection utility and is representative of all generated libraries with comparable feature sets.

This structure is not a template. It is enforced and verified mechanically on every build.

Each area has a single, well-defined responsibility.

Extract from:
(dev) C:\TestLibs\fs_lib>forge structure

├── .venv/                <- isolated environments
│   ├── user-core-313/
│   ├── dev-core-313/
│   ├── docs-core-313/
│   └── .venv_map.json
├── _build_state/         <- resolved lockfiles + observed state
├── docs/                 <- generated documentation
├── forge/                <- CLI facade
├── falcon_smith/         <- embedded engine internals
├── runtime/              <- embedded Python, uv, toolchains, wheels
│   └── dependency_manifest.json   <- the approved, hash-pinned state
├── src/fs_lib/           <- client library python code
│   ├── _native/          <- native source, artifacts, manifests
│   ├── io/               <- domain logic
│   ├── hooks/            <- extension points
│   └── portal/           <- Python gateway to compiled native artifacts
├── tests/                <- verification & contracts
├── check_runtime.bat     <- connect to the runtime share (once)
├── dev_setup.bat         <- rebuild everything from the foundation
├── falcon_env.toml
├── pyproject.toml
└── README.md

Any deviation from this structure is detected during verification.

Engine layer: falcon_smith/ + forge/

The embedded FalconSmith engine is two sibling packages: the engine internals and the stable CLI facade every workflow goes through.

forge/          <- user-facing CLI facade: forge <verb>
falcon_smith/   <- engine internals (build, scan, verify, expose, state)

• Bootstrapping and structure enforcement
• Native build orchestration
• Documentation scanning and generation
• Diagnostics, inventory, and verification

• The engine is structurally separate from project code
• Client code does not import engine internals at runtime
• The engine is delivered alongside the project and fully inspectable

This avoids hidden tooling and reduces long-term dependency on opaque build systems.

Project layer: src/<package_name>/

The src/ directory contains only project-specific code.

├── src/fs_lib/           <- client library code
│   ├── _native/          <- native source, artifacts, manifests
│   ├── io/               <- domain logic
│   ├── hooks/            <- extension points
│   └── portal/           <- Python gateway to compiled native artifacts
├── _version.py

• Domain logic is isolated from infrastructure
• Public APIs are explicit and discoverable
• Native code is accessed through controlled interfaces
• No build orchestration exists in this layer

From a contributor’s perspective, this is a conventional, clean Python package — with native acceleration exposed explicitly rather than hidden behind build magic.

Native layer: _native/

Native code is treated as a first-class component.

_native/
├── compiled/                 <- built binaries
│   └── exposed/              <- public native API surface
│       ├── flat/             <- default flat exposure (auto-generated)
│       ├── io/               <- user-defined exposure
│       └── exposed_api.json  <- explicit native exposure
├── src/                      <- native source (C++ / Rust)
├── portal/                   <- link to Python-visible interface
├── native_build_map.json
├── native_categories.json
├── native_compilation.json
└── version.json

• Source and artifacts are separated
• Multiple native languages can coexist
• Python runtime never depends on native build logic
• Interfaces are explicitly mapped and versioned

Parity between source, artifacts, and Python exposure is enforced.

The portal interface is generated from the native exposure manifest and reflects the exact set of functions defined in exposed_api.json.

Documentation layer: docs/

Documentation is generated from deterministic Python inventory scanning and explicit native API manifests, then rendered by Sphinx.

docs/
├── build/
├── source/
│   ├── _static/
│   ├── python/
│   │   ├── hooks/
│   │   │   └── native_reader_hooks.rst
│   │   ├── io/
│   │   │   └── native_readers.rst
│   │   ├── hooks.rst
│   │   ├── index.rst
│   │   └── io.rst
│   ├── conf.py
│   ├── forge.rst
│   ├── falcon_smith_engine.rst
│   ├── index.rst
│   └── portal.rst
└── MakeFile				<- Generated for sphinx

• API references reflect actual code
• Native interfaces are documented alongside Python
• Documentation builds in an isolated environment

Verification layer: tests/

Verification is part of the system, not an optional step.

tests/
├── demo/
├── falcon_smith/
├── hooks/
├── io/
├── runtime/
└── conftest.py

• The engine has explicit contracts
• Generated projects are validated against those contracts
• Native integration is tested explicitly
• Runtime state is tested explicitly - the embedded foundation is verified against the approved manifest, not assumed

Environment layer: .venv/

FalconSmith uses explicit, isolated Python environments:

.venv/
├── user-core-313/
├── dev-core-313/
├── docs-core-313/
└── .venv_map.json

• Dependency leakage is prevented
• Builds are reproducible
• Documentation can be built independently

Environment names encode role, profile, and Python version. For example, dev-core-313 means development environment, core profile, CPython 3.13.

Contributor perspective

• Most work happens in src/<package_name>/
• Native code lives under _native/src/
• Documentation is regenerated
• Tests validate structure and behavior
• Engine internals are rarely modified

What this structure optimizes for

• Long-term maintainability
• Safe refactoring
• Clear ownership boundaries
• Predictable builds
• Transparent verification

It does not optimize for minimal file count or ad-hoc experimentation.

Summary

The FalconSmith project structure encodes engineering decisions directly into the filesystem, enabling safe evolution without tribal knowledge.