Nyilvános oldal

A Teletype Games nyilvános platformja: egyetlen monorepó (services/teletypegames) a katalógus-backenddel (Catalog API) és a retró stílusú frontenddel, Docker Compose-zal futtatva.

A monorepó felépítése

TXT

apps/
  frontend/   # Vue 3 + Vite + TypeScript + Tailwind
  api/        # Rails 8 API + ActiveAdmin

A docker compose up -d elindítja a fejlesztői környezetet. Mindkét alkalmazás egy domain alatt van:

Útvonal	Mit szolgál ki
`/`	frontend
`/api`	Catalog API
`/admin`	ActiveAdmin
`/api/swagger`	API-dokumentáció

Lintelés: RuboCop (rubocop-rails-omakase) a backendhez, ESLint 9 (flat config, Vue + TypeScript) a frontendhez.

Catalog API

Rails 8 + MySQL. ActiveAdmin felület (blaze téma, Devise-hitelesítés), Blueprinter-szerializálók, apipie-rails dokumentáció böngészhető Swagger UI-jal. Ez az egyetlen igazságforrás a szoftver-metaadatokhoz, kiadásokhoz, tagokhoz, eseményekhez és letöltési naplókhoz, és ez szolgálja ki a képeket és binárisokat.

Domainmodell

A Software (name, title, author, desc, story, license, platform, status, highlighted; soft delete) sok Release és ExternalLink elemhez tartozik, valamint képekhez a SoftwareImage táblán keresztül (alapértelmezett jelző + sorrend). Egy Release tárolja a verziót, valamint a kazetta / forrás / HTML-mappa / dokumentációs mappa útvonalait. Minden letöltés egy Download sor (IP, user agent, referer, kiadás), ami downloadCount / totalDownloads néven jelenik meg az API-válaszokban.

Végpontok

Végpont	Mire való
`GET /api/software`	Katalóguslista: szoftver + rendezett kiadások + `latestRelease` (a `dev-` kihagyásával) + `webPlayableRelease` + `totalDownloads`
`GET /api/software/highlighted`	Kiemelt szoftverek
`GET /api/events`	Közösségi események
`GET /api/members`	Csapattagok
`GET /api/stores`	Áruház-nyilvántartás (lásd lentebb)
`GET /api/image/:id`	Képkiszolgálás
`GET /api/wiki/pages?tag=blog\\|howto[&limit][&body=1][&lang=en\\|hu]`	Wiki-proxy: a Grav `custom/pages.json` végpontját kéri le a `WIKI_GRAV_URL` alapján, így a frontend soha nem beszél közvetlenül a wikivel
`GET /api/rss/blog`	RSS a `blog` címkéjű wikioldalakról
`GET /api/rss/releases`	RSS a legfrissebb kiadásokról
`GET /api/download?path=…`	Naplózott letöltés (rögzíti az IP / UA / referer adatokat, majd kiszolgál)
`GET /api/swagger`	apipie-dokumentáció
`GET /file/*path`	Közvetlen fájlletöltés; az API-válaszok kiadásútvonalai ide mutatnak
`POST /build/upload`	Artifact-feltöltés, kérésenként egy fájl; alkalmazástoken `upload` jogosultsággal
`POST /build/publish`	Kiadás publikálása; alkalmazástoken `update` jogosultsággal, a CI hívja feltöltés után

A tokeneket a WarpEngine cikk írja le.

Az áruház-nyilvántartás (GET /api/stores) megmondja, mely katalógusokból telepíthet egy kliens, és hol van az egyes áruházak konfigurációja. Nyilvános, mert az asztali kliens első indításkor olvassa, és nincs kinek belépnie. Egy sor három mező (name, catalog_url, store_repository_url), az ActiveAdmin ▸ 🛒 Stores alatt szerkeszthető. A hosztalkalmazásban él, nem a WarpEngine-ben: a motor egyetlen katalógust szolgál ki, és nem tudja, ki szállít hozzá áruházakat.

Publikálási pipeline

A /build/publish platform szerint továbbít egy Platforms szolgáltatásnak (tic80, love, ebitengine, c64, plus4, godot, bevy, phaser). Mindegyik felveszi a feltöltött artifactokat (C64 és Plus/4 esetén <név>-<verzió>.prg + <név>-<verzió>.metadata.json, az EmulatorJS .html.zip és a yapeSDL -linux-x64, -win-x64, -mac-universal zipek), a metaadatból upserteli a Software rekordot, a site mezőből hozzáad egy Source Code külső linket, és létrehozza a Release rekordot. A Gitea + Woodpecker oldal az Üzembe helyezés cikkben van.

Frontend

Vue 3 SPA, Vitével építve, TypeScriptben: vue-router (oldalanként egy modul), Pinia-store-ok domainenként (software, events, members, git, blog, howtos, youtube, ui), vue-i18n, valamint Tailwind CSS + TuiCSS a retró terminál-kinézethez. A Traefik ugyanazon az alapdomainen proxyzza, mint az API-t.

Oldalak: home, catalog (lista + részletek), blog, code, howtos, team, contact. A katalógus részletoldalán képnagyító, kiadáslista, letöltésszámlálók és böngészőben játszható kiadások vannak.

Forrásonként egy kliensmodul a src/api/ alatt:

Modul	Forrás
`software.api.ts`, `event.api.ts`, `member.api.ts`	Catalog API
`wiki.api.ts`	A Catalog API wiki-proxyja (`blog` / `howto` címkék), a felület nyelvét `lang` paraméterként átadva. A `VITE_WIKI_BASE` csak a Gravra mutató külső linkek felépítéséhez kell
`git.api.ts`	Gitea REST API v1 (`WEBAPP_GITEA_TOKEN` token) a Code oldalhoz
`youtube.api.ts`	YouTube Data API: a csatorna legutóbbi videója és megtekintésszáma

Analitika. A useMatomo egyszer állítja fel a Matomo-trackert, és oldalmegtekintést csak a router afterEach-e mér, így egy látogatás egy oldalmegtekintés (korábban kettő volt). Az első navigáció megtartja a külső referrert, ahelyett hogy a saját / írná felül. A mérés sütimentes (disableCookies, nincs _pk_id, nem kell hozzájárulás), és egy heartbeat-időzítő az egyoldalas látogatások idejét is rögzíti. A Gitea-fejléc ugyanezt a trackert kapja.

CI

Workflow	Mikor fut	Mit csinál
`.woodpecker/deploy.yaml`	push a `master`re, kézzel	a `rubocop` és a `test-host` párhuzamosan, a `deploy` mindkettőt megvárja; a deploy egy SSH-hívás a szerveren a `ci-deploy teletypegames` parancsra
`.woodpecker/warp_engine.yaml`	a `libs/ruby/warp_engine` változásai	verzióellenőrzések, `rubocop` + `test-engine`, majd a split-mirror az `engines/warp_engine`-be és a gem publikálása
`.woodpecker/ci-images.yaml`	a `ci/**` vagy a gemeket meghatározó fájlok változása a `master`en, kézzel, éjszakai cron	megépíti az alábbi CI-image-eket

Egyik lépés sem kap hoszt-mappát vagy docker socketet, így semmihez nem kell trusted: volumes (a régi /srv/ci-cache volume megszűnt): az eszközök és a gemek saját CI-image-einkben vannak, amelyeket a ci/*.Dockerfile fájlokból a kaniko épít (privileged mód és docker socket nélkül), és a Gitea registrybe pushol a git.teletypegames.org/build/… alá:

Image	Ki használja
`teletypegames-ci:api-ruby3.3`	a `deploy.yaml` rubocop + test-host lépése (ruby 3.3, a mysql2 build-függőségei, az `apps/api` gemjei)
`teletypegames-ci:warp_engine-ruby3.2`	a `warp_engine.yaml` rubocop + test-engine lépése
`deploy-ssh:alpine3.22`	minden repó minden `ssh deploy@` deploy lépése, digest szerint hivatkozva
`dos-ci:bookworm`	a `dos/*` repók test lépése (Open Watcom, DOSBox, DOSBox Staging, Wine, clang-format)
`ci-tools:alpine3.22`	segédlépések: git, git-subtree, jq, curl, zip, lua, luacheck, ldoc — a WarpEngine `tools` image-e minden játék-pipeline-hoz (digest szerint), a release lépések, a split-mirror
`pyftpdlib:3.13`	az `infra/ftp-server` test lépése
`warp-engine-client-ci:node22`	a `stores/warp-engine-client` check lépése, előre telepített `node_modules`-szal
`ebitengine-ttg:latest`	a WarpEngine ebitengine-buildere: az `ebitengine-builder` a TTG összes Go-projektjének moduljaival
`bevy-ttg:latest`	a WarpEngine bevy-buildere: a `bevy-builder` a TTG összes Rust-projektjének crate-jeivel

Minden image kap egy mozgó és egy commithoz kötött taget (…-<commit>), és csak akkor épül újra, ha a masteren a saját Dockerfile-ja vagy a gemjeit meghatározó fájlok változnak, vagy kézzel. Kivétel a warp-engine-client-ci, az ebitengine-ttg és a bevy-ttg, amelyek függőségei más repókban vannak: ezeket az éjszakai ci-images-nightly cron is nézi, és csak akkor épít, ha az aktuális függőségekre még nincs image (lock-<sha> a kliens package-lock.json-jára; deps-<sha> a ci/collect-deps.sh által a games, demos és engines org minden ágáról összegyűjtött go.mod/go.sum és Cargo.toml/Cargo.lock fájlokra, plusz a builder digestjére). Egy új függőséget a build ugyanúgy letölt, mint eddig. A workflow egy secretet kér: forge_token (package:write).