STRUCTURE.md
Rama main · réplica de lectura del repositorio original.
# Repository Structure
<sub>[← README](README.md) · [Deploy](DEPLOY.md) · [Upgrading](docs/UPGRADING.md) · [Operations](docs/OPERATIONS.md) · **Structure** · [Contributing](CONTRIBUTING.md) · [Releasing](RELEASING.md) · [ADRs](docs/adr)</sub>
This is a **monorepo** for an MDM product forked from Headwind MDM. It contains four
cooperating planes plus shared protocol and docs.
```
.
├── server/ common/ jwt/ notification/ plugins/ # PLANE 1 — Control plane (forked Headwind, Java/Jersey/PostgreSQL)
│ pom.xml # (existing Maven multi-module project, builds launcher.war)
├── web/ # PLANE 2 — Admin frontend (new, React + Vite + TypeScript)
├── agent-android/ # PLANE 3 — Device agent (new, Kotlin Device-Owner app)
│ └── (remote-control transport lives in :remote) # PLANE 4 — Remote control (WebRTC + coturn, signaling over MQTT/long-poll)
├── proto/ # Shared protocol: capability matrix + command model (source of truth)
├── supervisor/ # Updater + recovery page (Node): polls releases, verifies, applies/rolls back
├── install/ # Native installer/uninstaller, shared shell libs (lib/), seed SQL, email templates
├── release/ # Release tooling: manifest build/sign/verify, APK checksum, minisign.pub
├── scripts/ # Dev + CI helpers: Agent v1 e2e, dev seed, edge check, supervisor smoke, shots/
├── tests/native/ # T2 rig: native install/upgrade in throwaway systemd containers
├── docs/adr/ # Architecture Decision Records (one-way-door choices)
├── reference/hmdm-android/ # gitignored study clone of upstream agent (Apache-2.0, NOT shipped)
└── docker/ docker-compose*.yml # Docker stack; dev = docker-compose.dev.yml overlay + docker/dev.env (docs/DEV.md)
```
`setup.sh` (Docker or `--native`) and `quickstart.sh` (published images) at the root are the install entry points.
## The four planes
| Plane | Path | Tech | Status |
|-------|------|------|--------|
| 1. Control plane | `server/` + `common/ jwt/ notification/ plugins/` | JDK 17, Jersey/JAX-RS, Guice, MyBatis, PostgreSQL, Liquibase | Forked from Headwind + extended; REST-only (legacy AngularJS UI removed) |
| 2. Admin frontend | `web/` | React 19, Vite, TypeScript | New, from scratch — the console |
| 3. Device agent | `agent-android/` | Kotlin, coroutines, Hilt, Room, WorkManager, kotlinx.serialization | New, with parts ported from the Headwind agent (see [NOTICE](NOTICE)) |
| 4. Remote control | `agent-android/remote/` + server signaling | MediaProjection + AccessibilityService, WebRTC, coturn | Stubbed |
## Two load-bearing architecture patterns
- **Capability-abstraction layer** (`agent-android/policy/`): every privileged op behind a
versioned interface with `SDK_INT`-gated strategies. Survives the Android version treadmill
by swapping one strategy instead of rewriting.
- **Server-driven command model + capability handshake** (`proto/`): the device advertises a
capability matrix on check-in; the server only issues commands the device advertises. The
protocol is versioned and schema-evolvable so old agents degrade gracefully.
## Why the existing server stays at repo root
The Headwind Maven project (root `pom.xml` + `common/ jwt/ notification/ plugins/ server/`) is
mature and its build/install scripts assume these paths. Nesting it under `server/` is a
deferred, optional cleanup — not worth the churn during foundation. New components get their
own top-level directories.
## Build & verify
See `docs/DEV.md` for the local dev loop. Server builds with Maven, web with npm/Vite, agent
with Gradle + the Android SDK. CI (`.github/workflows/`) runs in tiers: T0 builds and unit-tests the
planes a change touches, T1 runs the Agent v1 end-to-end suite, T2 the native install/upgrade rig. See
"CI" in [CONTRIBUTING.md](CONTRIBUTING.md#ci).