# Repository Structure (/docs/repository/structure)

The vMenu repository holds two products in one codebase:

| Product | Branch | Docs |
| --- | --- | --- |
| **vMenu Enhanced** (current) | `main` | [docs.vespura.com/vmenu/enhanced](https://docs.vespura.com/vmenu/enhanced/) |
| **vMenu Legacy** (v3.9.2 and below, frozen) | `legacy` | [docs.vespura.com/vmenu/legacy](https://docs.vespura.com/vmenu/legacy/) |

`main` contains the full Enhanced source. The `legacy` branch is the old vMenu, kept for
download and for the saved-data importer.

## Top level [#top-level]

| Path | What it is |
| --- | --- |
| `src/` | All C# source. Split into Enhanced, Legacy and Shared. |
| `docs/` | The Astro + Starlight site that produces docs.vespura.com. The markdown in `docs/src/content/docs` is the source of the published docs. |
| `assets/` | Images and branding: `enhanced/`, `legacy/`, `shared/`, `txadmin/`. |
| `dependencies/` | Vendored dependencies for the legacy build. |
| `tools/` | Helper projects: `ConfigDefaults`, `LanguageTemplate`, `LegacyChecks`, `vMenu.Enhanced.Localization.Generator`, `vMenu.Enhanced.NativeHooks.Generator`. |
| `.github/workflows/` | `combined.yml`, `dev-enhanced.yml`, `docs.yml` — CI and the docs deploy. |
| `vMenu.Enhanced.slnx` | The solution. |
| `LICENSE.md` | GPL-3.0-or-later. Authoritative over anything else that says so. |

## `src/` [#src]

```
src/
├── Enhanced/          # vMenu Enhanced (GTA V Enhanced + Legacy FiveM)
│   ├── Client/        # client-side runtime, menus, native hooks
│   ├── Server/        # server-side runtime, permissions, config, webhooks
│   └── PluginApi/     # the public plugin surface (ClientAPI / ServerAPI)
├── Legacy/            # the original vMenu, kept building
│   ├── Client/
│   ├── Server/
│   └── PluginApi/
└── Shared/            # code both builds compile in
    ├── vMenu.Enhanced.Data          # data model, settings, permissions, catalogs
    ├── vMenu.Enhanced.PluginContracts  # the shared plugin protocol
    ├── vMenu.Enhanced.PluginAnalyzers  # Roslyn analyzers that validate plugins
    ├── vMenu.Enhanced.Localization   # translation files and the Loc.* accessors
    ├── vMenu.Enhanced.JsAPI         # the JavaScript plugin API (TypeScript source, built with npm)
    ├── vMenu.Enhanced.LuaAPI        # the Lua plugin API (vmenu.lua)
    ├── vMenu.Enhanced.Logging       # logging primitives
    └── vMenu.Enhanced.Polyfills     # polyfills for older runtimes
```

### `src/Enhanced/Client` [#srcenhancedclient]

| Project | Responsibility |
| --- | --- |
| `vMenu.Enhanced.Actions` | The things a player can do (freeze, teleport, explode, …). |
| `vMenu.Enhanced.BrokenNatives` | Workarounds for natives that misbehave. |
| `vMenu.Enhanced.Configuration` | Client-side reading of the server config. |
| `vMenu.Enhanced.Core` | Client entry point. |
| `vMenu.Enhanced.Events` | Client-side event plumbing. |
| `vMenu.Enhanced.MenuFramework` | The menu renderer, themes and layout. |
| `vMenu.Enhanced.Menus` | Every menu the player sees. |
| `vMenu.Enhanced.NativeHooks` | Hooks into GTA natives. |
| `vMenu.Enhanced.NoClip` | The noclip feature. |
| `vMenu.Enhanced.Permissions` | Client-side permission state and sync. |
| `vMenu.Enhanced.Plugins` | Client-side plugin host. |
| `vMenu.Enhanced.Serialization` | Reading and writing saved data. |
| `vMenu.Enhanced.Storage` | Where saved data lives on disk. |
| `vMenu.Enhanced.Ticks` | The tick scheduler. |

### `src/Enhanced/Server` [#srcenhancedserver]

| Project | Responsibility |
| --- | --- |
| `vMenu.Enhanced.Actions.Server` | Server-side validation of player actions. |
| `vMenu.Enhanced.BrokenNatives.Server` | Server-side native workarounds. |
| `vMenu.Enhanced.Configuration.Server` | The `configuration.cfg` writer and the example file. |
| `vMenu.Enhanced.Core.Server` | Server entry point. |
| `vMenu.Enhanced.Http.Server` | Outbound HTTP, used by webhooks and the integration API. |
| `vMenu.Enhanced.Integration.Server` | The SnowstormBot / role-sync integration. |
| `vMenu.Enhanced.Permissions.Server` | The permission registry and the `permissions.cfg` writer. |
| `vMenu.Enhanced.Players.Server` | Player state. |
| `vMenu.Enhanced.Plugins.Server` | Server-side plugin host. |
| `vMenu.Enhanced.Serialization.Server` | Server-side saved-data handling. |
| `vMenu.Enhanced.Ticks.Server` | Server-side tick scheduler. |
| `vMenu.Enhanced.Updates.Server` | Update checking. |
| `vMenu.Enhanced.Webhooks.Server` | Discord webhook logging. |
| `vMenu.Enhanced.World.Server` | The World API surface. |

## Where the reference material lives [#where-the-reference-material-lives]

| What | Where in the source |
| --- | --- |
| Every configuration setting (name, type, default, description) | `src/Shared/vMenu.Enhanced.Data/Configuration/Settings/*.cs` |
| The order settings are written into `configuration.cfg` | `src/Shared/vMenu.Enhanced.Data/Configuration/ConfigCatalog.cs` |
| Every permission, grouped by category | `src/Shared/vMenu.Enhanced.Data/Permissions/` |
| How the dotted permission scheme resolves inheritance | `src/Shared/vMenu.Enhanced.Data/Permissions/PermissionPath.cs` |
| The generated `permissions.cfg` example | `src/Shared/vMenu.Enhanced.Data/Permissions/PermissionsExample.cs` |
| The generated `configuration.cfg` example | `src/Shared/vMenu.Enhanced.Data/Configuration/ConfigurationExample.cs` |
| The plugin protocol shared by both sides | `src/Shared/vMenu.Enhanced.PluginContracts/` |
| The public plugin surface for C# plugins | `src/Enhanced/PluginApi/vMenu.Enhanced.ClientAPI/` and `.../vMenu.Enhanced.ServerAPI/` |
| The JavaScript and Lua plugin surfaces | `src/Shared/vMenu.Enhanced.JsAPI/src/` (TypeScript), `src/Shared/vMenu.Enhanced.LuaAPI/vmenu.lua` |
| The published documentation source | `docs/src/content/docs/` |

## Building [#building]

The solution targets .NET with a `global.json` pinning the SDK. `nuget.config` points at the
package feeds. The legacy build pulls vendored binaries from `dependencies/legacy`.

The docs site is a separate npm project inside `docs/` (`npm install && npm run build`), and
`docs.yml` in CI deploys it to docs.vespura.com.