# MrixsCraft

Private Minecraft server project with a web-based launcher.

## Architecture

Consists of two independent Go repositories unified via git submodules:

- **`server/`** — backend (Go + net/http + PostgreSQL)
- **`launcher/`** — desktop launcher (Go + Fyne GUI)

Both are **separate Go modules** — they have their own `go.mod`, tests, and can be built independently. The only connection between them is HTTP API (Yggdrasil + REST).

Domain: `minecraft.mrixs.me` · CDN: `cdn.mrixs.me` · Registry: `gitea.mrixs.me`

---

## Documentation

| File | Purpose |
|------|---------|
| `docs/state.md` | **Current project status** — architecture, API, DB schema, TODOs. Read this first. |
| `docs/server/Specification.md` | Server specification (RU) |
| `docs/launcher/Specification.md` | Launcher specification (RU) |

**Rule:** Read `docs/state.md` first. During work, compare implementation against specifications. Update `docs/state.md` when something changes.

---

## Working with Submodules

`server/` and `launcher/` are **git submodules**, not regular directories. Each tracks its own remote:

```
launcher → ssh://git@gitea.mrixs.me:2222/Mrixs/MrixsCraft-launcher.git
server   → ssh://git@gitea.mrixs.me:2222/Mrixs/MrixsCraft-server.git
```

### Workflow

```bash
# 1. Enter submodule
cd server/    # or launcher/

# 2. Edit code
# ...

# 3. Build & test locally
go build ./...
go test ./...

# 4. Commit INSIDE the submodule
git add -A
git commit -m "feat: ..." -m "Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"

# 5. Push the submodule
git push origin master

# 6. (Optional) Return to parent and record the new submodule commit
cd ..
git add server   # or launcher
git commit -m "chore: bump server submodule"
```

**Always commit and push inside the submodule first.** CI/CD is triggered by pushes to submodule repos, not the parent.

### Clone

```bash
git clone --recurse-submodules gitea.mrixs.me:mrixs/mrixscraft.git MC-server
```

If already cloned without submodules:
```bash
git submodule update --init --recursive
```

---

## Server (`server/`)

### Key Paths

| Path | Purpose |
|------|---------|
| `cmd/server/main.go` | Entry point — routes, middleware, graceful shutdown |
| `internal/auth/` | Yggdrasil auth (authenticate/refresh/validate) |
| `internal/api/` | Public API (register, login, skins, capes, launcher) |
| `internal/admin/` | Admin panel (modpacks, uploads, manifests) |
| `internal/cas/` | Content-Addressable Storage (SHA-1 file serving) |
| `internal/templates/` | Website pages (embedded via `go:embed`) |
| `migrations/` | SQL migrations (manual apply) |
| `Dockerfile` | Multi-stage build (~20 MB) |
| `.gitea/workflows/ci.yml` | CI: lint → test → build → docker push |

### Build & Test

```bash
cd server/
go build -o mrixscraft-server ./cmd/server
go test ./... -race -cover
```

### Environment Variables

| Variable | Default | Required |
|----------|---------|----------|
| `SERVER_PORT` | `8080` | No |
| `DATABASE_URL` | — | **Yes** |
| `CAS_DIR` | `/var/www/cdn/files` | No |
| `JWT_SECRET` | — | **Yes** |
| `BASE_URL` | `https://minecraft.mrixs.me` | No |

---

## Launcher (`launcher/`)

### Key Paths

| Path | Purpose |
|------|---------|
| `cmd/launcher/main.go` | Entry point, Fyne bootstrap |
| `internal/auth/` | Yggdrasil client |
| `internal/config/` | `launcher.json`, system paths |
| `internal/fetcher/` | HTTP downloader with SHA-1 verification |
| `internal/java/` | JRE detection/download |
| `internal/launch/` | Manifest parsing, game launch |
| `internal/selfupdate/` | Binary auto-updater |
| `internal/ui/` | Fyne GUI (screens, components, theme) |

### Build

```bash
cd launcher/
go build -o mrixscraft-launcher ./cmd/launcher
go run ./cmd/launcher
```

---

## Deployment Flow

```
[Commit + push inside submodule]
         │
         ▼
  [Gitea Actions CI]
  lint → test → build → docker push
         │
         ▼
  [Gitea Container Registry]
  gitea.mrixs.me/mrixs/mrixscraft-server:latest
         │
         ▼
  [Watchtower on VPS]
  polls every 5 min → pull → restart
```

**No manual deployment needed.** Push to submodule → auto-deploy.

Required Gitea secrets: `PACKAGES_TOKEN` (PAT with `read:package`, `write:package`).

---

## Style Guidelines

- Use Markdown (`.md`) for documentation
- Go: stdlib `net/http`, `html/template` with `go:embed`, `pgx/v5` for DB
- Dark theme (#0f0f1a / #16213e) with green accent (#4ade80) for web templates
- Commit message format: `type: description`

---

## Git Conventions

```
type: short description

longer body if needed
```

Types: `feat`, `fix`, `chore`, `refactor`, `docs`

---

## Port Reference

| Service | Port | Scope |
|---------|------|-------|
| server (backend) | 8080 | Internal (Docker) |
| PostgreSQL | 5432 | Internal (Docker) |
| Caddy | 80, 443 | Public |