# krishnansg/codeenigma architecture
> Architecture diagram of the GitHub repository krishnansg/codeenigma, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/krishnansg/codeenigma
- Repository: https://github.com/krishnansg/codeenigma
## Overview
1. **What this repo is**
CodeEnigma is a Python source-obfuscation tool. Its architecture is a build-time pipeline: it takes a Python package/module as input, transforms the code into encrypted payloads, and emits a distributable package that depends on a compiled runtime to decrypt and execute the protected code.
2. **Primary entrypoints**
The user-facing surface is the CLI in `codeenigma/cli.py`. That CLI feeds into `codeenigma/orchestrator.py`, which appears to coordinate the full obfuscation flow. The CLI is the only direct interactive boundary; everything else is internal build machinery.
3. **Core orchestration flow**
The orchestration layer ties together four phases:
- inspect and bundle the target module,
- transform each source file into an obfuscated payload,
- generate runtime/loading code,
- compile the runtime into a native Python extension via Cython.
This makes the architecture a source-to-artifact pipeline rather than a long-running application.
4. **Bundling subsystem**
`codeenigma/bundler/` contains the logic for collecting source files from a project layout. The presence of `standard.py` and `poetry.py` suggests two supported project shapes: a generic Python package layout and Poetry-managed projects. This subsystem is responsible for discovering the module boundary and preparing files for transformation.
5. **Obfuscation strategy layer**
`codeenigma/strategies/` defines how code is transformed. The concrete implementation in `encryption.py` matches the README pipeline: compile Python source to bytecode, compress it, encode it, and encrypt it. The `base.py` module likely defines the abstraction that lets orchestration swap or extend transformation strategies.
6. **Encryption runtime contract**
The obfuscated payload is useless without the companion runtime. `codeenigma/strategies/encryption_runtime.py.template` and `codeenigma/executor.py.template` indicate that CodeEnigma generates a loader/executor that knows how to decrypt payloads and execute them at import/runtime. This is a clear boundary: build-time encryption lives in Python code, while execution-time decryption is embedded into generated runtime code.
7. **Compiled runtime subsystem**
`codeenigma/runtime/` is the runtime generation and build layer. The `cython/` subpackage contains templates for `init.py`, `setup.py`, and `pyproject.toml`, plus a `builder.py`, indicating the project compiles the runtime into a Cython extension module. This compiled boundary is important: the protected app ships with a native extension that performs decryption/loading logic instead of plain Python source.
8. **Extensions subsystem**
`codeenigma/extensions/` adds optional cross-cutting features to the obfuscation output. The concrete `expiry.py` module and its `expiry_code.py.template` show that the repository supports injecting expiration behavior into the generated runtime, so protected code can be made time-limited. This is an augmentation layer rather than the main encryption mechanism.
9. **Secret material and generated state**
`codeenigma/private.py` is the likely home for generated secret key material or runtime constants used during obfuscation. The README explicitly says an AES-256 key is generated and set in `private.py`, so this file is part of the internal trust boundary and should not be treated as regular source code in the final distribution.
10. **Templates as code-generation assets**
Several `.template` files are central to the architecture: they are used to stamp out the runtime loader, Cython packaging files, and expiry logic. This indicates CodeEnigma is a code generator as much as an obfuscator; it synthesizes a new package structure around the protected payload rather than mutating the original project in place.
11. **Test and fixture architecture**
`tests/example_module/` is a representative sample project used to validate end-to-end behavior. `tests/test_e2e.py` likely exercises the full pipeline from input module to generated artifact, while `tests/test_version.py` covers package metadata/versioning. The tests reinforce that the repo’s main contract is “input project in, obfuscated distributable out.”
12. **External dependencies that shape the design**
The architecture depends on `cryptography` for AES-GCM encryption and `Cython` for building the runtime extension. Poetry support is also first-class, both for project detection and packaging. These tools are not incidental; they define the artifact boundary and the way the obfuscated output is packaged for distribution.
13. **Resulting system boundary**
From an architecture-diagram perspective, CodeEnigma sits between a Python source tree and a compiled distributable wheel/package. The input side is plain Python modules; the output side is an obfuscated package plus a native runtime extension. The critical internal flow is: discover files → transform and encrypt → generate runtime templates → compile runtime → emit distribution artifacts.
Main entry points: [`codeenigma/orchestrator.py`](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/orchestrator.py) (Orchestrator), [`codeenigma/runtime/cython/builder.py`](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/cython/builder.py) (Cython builder), [`codeenigma/bundler/base.py`](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/bundler/base.py) (Bundle API), [`codeenigma/strategies/encryption.py`](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/strategies/encryption.py) (Encryption)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_grp_entry["Entry"]
node_cli["CLI
command entrypoint
[cli.py]"]
node_orchestrator["Orchestrator
pipeline coordinator
[orchestrator.py]"]
end
subgraph group_grp_bundle["Bundling"]
node_bundler_base["Bundle API
bundler abstraction
[base.py]"]
node_bundler_standard["Standard bundler
package layout bundler
[standard.py]"]
node_bundler_poetry["Poetry bundler
[poetry.py]"]
end
subgraph group_grp_transform["Transform"]
node_strategy_base["Strategy API
transform abstraction
[base.py]"]
node_encryption_strategy["Encryption
obfuscation strategy
[encryption.py]"]
node_strategy_runtime_tpl["Runtime tpl
loader template"]
node_private_state["Private state
secret material
[private.py]"]
end
subgraph group_grp_runtime["Runtime"]
node_runtime_base["Runtime API
runtime abstraction
[base.py]"]
node_runtime_builder["Cython builder
native build step
[builder.py]"]
node_runtime_init_tpl["Init tpl
runtime template
[init.py.template]"]
node_runtime_setup_tpl["Setup tpl
build template
[setup.py.template]"]
node_runtime_pyproject_tpl["Pyproject tpl
build template"]
node_executor_tpl["Executor tpl
loader template"]
end
subgraph group_grp_ext["Extensions"]
node_expiry_extension["Expiry
output extension
[expiry.py]"]
node_expiry_tpl["Expiry tpl
extension template"]
end
subgraph group_grp_tests["Tests"]
node_tests_sample["Sample app
fixture project"]
node_tests_e2e["E2E test
integration test
[test_e2e.py]"]
end
node_cli -->|"invokes"| node_orchestrator
node_orchestrator -->|"selects"| node_bundler_base
node_bundler_base -.->|"implements"| node_bundler_standard
node_bundler_base -.->|"implements"| node_bundler_poetry
node_orchestrator -->|"uses"| node_strategy_base
node_strategy_base -.->|"implements"| node_encryption_strategy
node_encryption_strategy -->|"generates"| node_strategy_runtime_tpl
node_encryption_strategy -->|"reads/writes"| node_private_state
node_orchestrator -->|"builds"| node_runtime_base
node_runtime_base -.->|"implements"| node_runtime_builder
node_runtime_builder -->|"renders"| node_runtime_init_tpl
node_runtime_builder -->|"renders"| node_runtime_setup_tpl
node_runtime_builder -->|"renders"| node_runtime_pyproject_tpl
node_runtime_builder -->|"embeds"| node_executor_tpl
node_orchestrator -.->|"optional"| node_expiry_extension
node_expiry_extension -->|"renders"| node_expiry_tpl
node_orchestrator -.->|"validates on"| node_tests_sample
node_tests_sample -.->|"exercised by"| node_tests_e2e
node_orchestrator -.->|"verified by"| node_tests_e2e
click node_cli "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/cli.py"
click node_orchestrator "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/orchestrator.py"
click node_bundler_base "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/bundler/base.py"
click node_bundler_standard "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/bundler/standard.py"
click node_bundler_poetry "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/bundler/poetry.py"
click node_strategy_base "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/strategies/base.py"
click node_encryption_strategy "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/strategies/encryption.py"
click node_strategy_runtime_tpl "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/strategies/encryption_runtime.py.template"
click node_private_state "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/private.py"
click node_runtime_base "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/base.py"
click node_runtime_builder "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/cython/builder.py"
click node_runtime_init_tpl "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/cython/init.py.template"
click node_runtime_setup_tpl "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/cython/setup.py.template"
click node_runtime_pyproject_tpl "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/cython/pyproject.toml.template"
click node_executor_tpl "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/executor.py.template"
click node_expiry_extension "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/extensions/expiry.py"
click node_expiry_tpl "https://github.com/krishnansg/codeenigma/blob/main/codeenigma/extensions/expiry_code.py.template"
click node_tests_sample "https://github.com/krishnansg/codeenigma/tree/main/tests/example_module"
click node_tests_e2e "https://github.com/krishnansg/codeenigma/blob/main/tests/test_e2e.py"
classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_orchestrator toneBlue
class node_bundler_base,node_bundler_standard,node_bundler_poetry toneAmber
class node_strategy_base,node_encryption_strategy,node_strategy_runtime_tpl,node_private_state toneMint
class node_runtime_base,node_runtime_builder,node_runtime_init_tpl,node_runtime_setup_tpl,node_runtime_pyproject_tpl,node_executor_tpl toneRose
class node_expiry_extension,node_expiry_tpl toneIndigo
class node_tests_sample,node_tests_e2e toneTeal
```
## Components
### Entry
User-facing command entrypoint and orchestration boundary.
- [CLI](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/cli.py): command entrypoint · User-facing interface for invoking obfuscation runs. · `codeenigma/cli.py`
- [Orchestrator](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/orchestrator.py): pipeline coordinator · Coordinates the full build-time obfuscation flow. · `codeenigma/orchestrator.py`
### Bundling
Project discovery and source collection for supported layouts.
- [Bundle API](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/bundler/base.py): bundler abstraction · Shared interface for project discovery and file collection. · `codeenigma/bundler/base.py`
- [Standard bundler](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/bundler/standard.py): package layout bundler · Handles generic Python package/module layouts. · `codeenigma/bundler/standard.py`
- [Poetry bundler](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/bundler/poetry.py): poetry bundler · Handles Poetry-managed project layouts. · `codeenigma/bundler/poetry.py`
### Transform
Code obfuscation and payload generation pipeline.
- [Strategy API](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/strategies/base.py): transform abstraction · Defines the interface for source transformation strategies. · `codeenigma/strategies/base.py`
- [Encryption](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/strategies/encryption.py): obfuscation strategy · Compiles, compresses, encodes, and encrypts Python source into payloads. · `codeenigma/strategies/encryption.py`
- [Runtime tpl](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/strategies/encryption_runtime.py.template): loader template · Template for generating the decrypt-and-execute runtime contract. · `codeenigma/strategies/encryption_runtime.py.template`
- [Private state](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/private.py): secret material · Generated keys and internal constants used during obfuscation. · `codeenigma/private.py`
### Runtime
Generated loader and compiled execution runtime.
- [Runtime API](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/base.py): runtime abstraction · Shared runtime generation and build interface. · `codeenigma/runtime/base.py`
- [Cython builder](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/cython/builder.py): native build step · Builds the runtime extension from generated sources and templates. · `codeenigma/runtime/cython/builder.py`
- [Init tpl](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/cython/init.py.template): runtime template · Template for the runtime package initializer. · `codeenigma/runtime/cython/init.py.template`
- [Setup tpl](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/cython/setup.py.template): build template · Template for the Cython packaging setup file. · `codeenigma/runtime/cython/setup.py.template`
- [Pyproject tpl](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/runtime/cython/pyproject.toml.template): build template · Template for the Cython build configuration. · `codeenigma/runtime/cython/pyproject.toml.template`
- [Executor tpl](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/executor.py.template): loader template · Template for the generated executor that runs protected code. · `codeenigma/executor.py.template`
### Extensions
Optional cross-cutting features injected into generated output.
- [Expiry](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/extensions/expiry.py): output extension · Injects time-limited behavior into the generated runtime. · `codeenigma/extensions/expiry.py`
- [Expiry tpl](https://github.com/krishnansg/codeenigma/blob/main/codeenigma/extensions/expiry_code.py.template): extension template · Template for generating expiry enforcement code. · `codeenigma/extensions/expiry_code.py.template`
### Tests
End-to-end validation and sample input project.
- [Sample app](https://github.com/krishnansg/codeenigma/tree/main/tests/example_module): fixture project · Representative target project used for end-to-end validation. · `tests/example_module`
- [E2E test](https://github.com/krishnansg/codeenigma/blob/main/tests/test_e2e.py): integration test · Exercises the full obfuscation pipeline on the sample project. · `tests/test_e2e.py`
## Connections
- CLI → Orchestrator: invokes · CLI hands control to the build pipeline coordinator.
- Orchestrator → Bundle API: selects · Orchestration starts by choosing a bundling strategy.
- Bundle API → Standard bundler: implements · Standard project layout is one supported bundler.
- Bundle API → Poetry bundler: implements · Poetry project layout is another supported bundler.
- Orchestrator → Strategy API: uses · Orchestration depends on a transformation strategy abstraction.
- Strategy API → Encryption: implements · Encryption is the concrete obfuscation strategy.
- Encryption → Runtime tpl: generates · Encryption strategy emits runtime loader code.
- Encryption → Private state: reads/writes · Strategy uses generated secrets and internal constants.
- Orchestrator → Runtime API: builds · Orchestration hands off runtime generation and compilation.
- Runtime API → Cython builder: implements · Cython builder is the concrete runtime build path.
- Cython builder → Init tpl: renders · Builder stamps out runtime package initialization code.
- Cython builder → Setup tpl: renders · Builder stamps out packaging setup metadata.
- Cython builder → Pyproject tpl: renders · Builder stamps out Cython build configuration.
- Cython builder → Executor tpl: embeds · Generated runtime includes the executor loader contract.
- Orchestrator → Expiry: optional · Expiry is an optional augmentation applied to output.
- Expiry → Expiry tpl: renders · Expiry feature injects generated enforcement code.
- Orchestrator → Sample app: validates on · Sample project represents the supported input shape.
- Sample app → E2E test: exercised by · End-to-end test runs the full pipeline against the fixture.
- Orchestrator → E2E test: verified by · Integration tests cover the end-to-end pipeline contract.