# Project Architecture

The toolkit patches IMVU Classic assets without modifying `IMVUClient.exe`.

## IMVU Classic Files

Relevant default paths:

```text
%APPDATA%\IMVUClient\
  IMVUClient.exe
  library.zip
  ui\chrome\imvuContent.jar
```

`library.zip` contains Python runtime code used by IMVU Classic.
`imvuContent.jar` contains embedded Gecko UI assets.

## Repository Layout

| Path | Purpose |
| --- | --- |
| `src/imvu_toolkit/` | Installable Python package |
| `src/imvu_toolkit/patches/emoji/` | Emoji patch parser, transforms, and apply/restore entrypoint |
| `src/imvu_toolkit/patches/dpi/` | Registry that exposes DPI patch scripts through the CLI |
| `src/imvu_toolkit/tools/` | Registry that exposes utility scripts through the CLI |
| `emoji_assets/js/` | JavaScript injected into IMVU chat |
| `patches/dpi/` | DPI patch scripts kept in legacy script form |
| `scripts/` | Probes, scaling helper, catalog generator, release helpers |
| `tests/` | Pytest suite with fixtures for transforms and integration behavior |
| `docs/` | Reference docs and this wiki |

Root-level scripts such as `patch_imvu_emoji.py` are backward-compatible
wrappers.

## CLI Shape

The package exposes:

```powershell
python -m imvu_toolkit emoji install
python -m imvu_toolkit emoji restore
python -m imvu_toolkit emoji generate-list
python -m imvu_toolkit tools scale-window
python -m imvu_toolkit dpi clean-layout
```

The `dpi` and `tools` subcommands pass extra flags through to legacy scripts.
Use `--` before script-specific flags:

```powershell
python -m imvu_toolkit dpi clean-layout -- --restore
```

## Patch Safety

The patch model is deliberately conservative:

- Detect whether IMVU is running before mutating files.
- Create timestamped backups before replacing targets.
- Use patch markers so re-runs can detect existing changes.
- Restore from newest matching backups.
- Fail fast when expected source signatures are missing.

## Release Pipeline

CI runs Ruff and pytest on Linux for pushes and pull requests. On pushes to
`main` or `master`, the Windows build job creates `dist/IMVU-Emoji-Installer.exe`
as an artifact.

Pushing a `v*` tag runs the release workflow:

1. Build the installer on Windows.
2. Extract release notes from `CHANGELOG.md`.
3. Append SHA256 and VirusTotal information.
4. Publish the GitHub Release with the `.exe` asset.

## Related Docs

- [Detailed architecture](../architecture.md)
- [Development Guide](Development-Guide.md)
- [Release Checklist](Release-Checklist.md)