# Architecture

This page documents the technical architecture of `conda-pypi`, explaining
how it integrates with conda and the internal organization of its components.

## Plugin System Integration

`conda-pypi` is implemented as a conda plugin using `conda`'s official plugin
architecture. This design enables seamless integration with conda's existing
workflows without requiring modifications to conda itself.

The plugin registers several hooks with `conda`'s plugin system. The
subcommand hook adds the `conda pypi` subcommand to conda through
`conda_pypi.plugin.conda_subcommands()`, providing both `conda pypi install`
for installing PyPI packages with conversion and `conda pypi convert` for
converting PyPI packages without installing them.

The plugin also registers three post-command hooks that extend conda's
existing commands. The environment protection hook triggers after `install`,
`create`, `update`, and `remove` commands to automatically deploy
`EXTERNALLY-MANAGED` files that prevent accidental `pip` (or any other Python install tool) usage. This is
implemented through `ensure_target_env_has_externally_managed()`.

## Data Flow Architecture

### Installation Flow

```
conda pypi install package
         ↓
CLI Argument Parsing
         ↓
Environment Validation
         ↓
Package Classification
         ↓
    VCS/Editable? ----Yes---→ Direct pip install --> Deploy EXTERNALLY-MANAGED
         ↓ No
Dependency Resolution
         ↓
Channel Search for Dependencies
         ↓
Convert Missing from PyPI
         ↓
Install via conda
         ↓
Deploy EXTERNALLY-MANAGED
```

### Conversion Flow

```
conda pypi convert package
         ↓
Fetch from PyPI
         ↓
Download Wheels
         ↓
Convert to .conda
         ↓
Save to Output Directory
```

### Plugin Hook Flow

```
conda command executed
         ↓
Post-command hook?
    ↓        ↓           ↓
list      install/    install/create/
--explicit  create     update/remove
    ↓        ↓           ↓
Add PyPI  Process    Deploy
lines     PyPI       EXTERNALLY-
    ↓     lines      MANAGED
Output to   ↓           ↓
stdout   Install    Create marker
         PyPI       files
         packages
```

## Key Design Principles

The architecture of `conda-pypi` is built around several key design
principles that ensure effective integration between conda and PyPI
ecosystems.

Conda-native integration is achieved by using `conda`'s official plugin
system and leveraging `conda`'s existing infrastructure including solvers,
channels, and metadata systems. This approach maintains full compatibility
with existing conda workflows.

This hybrid approach ensures that explicit packages always come
from PyPI to respect user intent, while dependencies prefer conda channels
for ecosystem compatibility. The system falls back to PyPI conversion only
when needed.

This architecture enables conda-pypi to provide a seamless bridge between
the conda and PyPI ecosystems while maintaining the integrity and benefits of
both package management systems.