MrixsCraft/CLAUDE.md

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

# 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

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

If already cloned without submodules:

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

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

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