Fabryka aplikacji TRL

1. Wstęp — o czym jest to szkolenie

Wyobraź sobie fabrykę samochodów. Ktoś przychodzi i mówi: „chcę czerwony samochód z 4 drzwiami, dla rodziny z dwójką dzieci". Fabryka go robi — sama. Robotnicy wiedzą jak. Linia produkcyjna jest gotowa. Materiały na półce. Kontrola jakości na końcu. Klient odbiera gotowy produkt.

U nas jest fabryka aplikacji. Zamiast samochodów produkujemy aplikacje — takie co działają jako strona internetowa, jako apka na telefonie z Androidem i jako apka na iPhone'a. Ktoś (np. Tomasz, właściciel firmy) wpisuje w jednym pliku buduj.txt, czego chce — i fabryka robi resztę.

Kto wykonuje robotę

• Sztuczna inteligencja — konkretnie program „Claude Opus" od firmy Anthropic. To „programista", który nie śpi, nie męczy się i pracuje dwa rzędy szybciej od człowieka.
• Ty (i zespół) — jak brygadzista. Mówisz co ma być zrobione, sprawdzasz czy dobrze, zatwierdzasz i wysyłasz na produkcję.

Do kogo to szkolenie

• Nowy członek zespołu — żebyś po przeczytaniu wiedział gdzie kliknąć, co czytać i czego nie ruszać.
• Każdy w GFT, kto chce zrozumieć cały proces zamiast szukać po komunikatorze.
• Zewnętrzny człowiek (np. kontraktor) — zanim coś nam zmieni, musi to przeczytać.

Kim jest właściciel

Tomasz (mail: t@gft.pl) — założyciel firmy. Sam nie programuje. Buduje całą fabrykę tak, żeby pisała aplikacje za niego. Każda apka, którą wypuszcza, ma od pierwszego dnia podpięte płatności (Stripe albo Lemon Squeezy — to bramki płatnicze, jak terminal w sklepie). Decyzje techniczne są zapisane w pliku CLAUDE.md i są nienegocjowalne.

2. Słownik — angielskie słowa, które się powtarzają

Te słowa pojawiają się w tekście wielokrotnie. Tu wyjaśniam co znaczą — żeby potem nie tłumaczyć przy każdym wystąpieniu.

Słów technicznych w tym materiale jest dużo. Jeśli któreś jeszcze nie ma w słowniku — kliknij Ctrl+F (szukaj na stronie) i wpisz słowo, prawdopodobnie jest gdzieś wytłumaczone w kontekście.

3. Po co fabryka — co rozwiązuje

Klasyczne robienie aplikacji na 3 platformy (strona, Android, iPhone) trwa pół roku do roku. Bo:

• Stronę pisze się w jednym języku (np. JavaScript / React)
• Apkę na Androida w innym (Kotlin albo Java)
• Apkę na iPhone'a w trzecim (Swift, dodatkowo wymaga Maca z Apple do testowania)
• Backend (część serwerowa) osobno
• Wdrożenie ręcznie — kupujesz serwer, konfigurujesz, ustawiasz HTTPS, walczysz
• Płatności — podłączasz Stripe, piszesz obsługę faktur, VAT-u, abonamentów

U nas fabryka łamie ten schemat. Jak?

Trzy żelazne zasady

1. Żaden krok nie może być pominięty. Nie ma „szybkiego wdrożenia bez testów" albo „małej poprawki bez planu". Idziesz po kolei albo wcale.
2. Każdy krok ma bramkę na wyjściu. Bramka = automatyczny test, który mówi „zielono — idź dalej" albo „czerwono — wracaj i napraw". Bez bramki nie idziesz dalej.
3. Spec (testy akceptacyjne) są jedynym dowodem że coś jest skończone. Nie kod. Bug w produkcji = najpierw piszemy nowy test, potem fix.

Jeden kod = trzy platformy

Expo = framework (gotowy szkielet), w którym piszesz raz a działa na 3 platformach. EAS = Expo Application Services — usługa firmy Expo, która kompiluje Twoją apkę w chmurze i wysyła do Apple oraz Google.

4. System TRL 1–9 — poziomy gotowości

TRL = Technology Readiness Level, czyli „poziom gotowości technologii". Skala od 1 do 9, wymyślona przez NASA w 1968 roku do oceny gotowości technologii kosmicznych: TRL 1 to pomysł na kartce, TRL 9 to coś, co już lata w kosmosie.

U nas w fabryce TRL pasuje idealnie:

• TRL 1 = pomysł zapisany w pliku buduj.txt
• TRL 9 = pierwsza prawdziwa zapłata od użytkownika w Stripe

Tabela poziomów

Sentry = system, który łapie błędy w apce i wysyła nam alarm. TestFlight = aplikacja Apple, w której testerzy mogą zainstalować nieopublikowaną jeszcze wersję iOS. Internal Testing = to samo dla Androida w Google Play. Retention = ile osób wraca do apki kolejnego dnia / tygodnia.

Foldery na dysku

Każdy poziom TRL ma swój folder. Apka „mieszka" w folderze odpowiadającym jej obecnemu poziomowi i przesuwa się dalej tylko po przejściu bramki.

Promocja apki z poziomu na poziom = przeniesienie folderu. Nie ruszaj tego ręcznie — robi to za nas TRL Store (panel zarządzający fabryką). Ręczne przesuwanie psuje katalog.

5. Gdzie co leży na dysku

Główny folder

Wszystko żyje pod ścieżką d:\6 APK APP TRL UP\. To „korzeń" całej fabryki.

Foldery TRL 1–9

O nich była mowa wyżej — to półki produkcyjne z aplikacjami w różnych stanach gotowości.

Specjalne foldery

6. Z czego są zbudowane apki — stack

Stack (po polsku „stos technologiczny") = zestaw narzędzi i bibliotek, których używamy do budowania apek. U nas jest jeden, ustalony — nie wybierasz go od projektu do projektu.

Decyzje są zapisane w konstytucji CLAUDE.md i są nienegocjowalne. Gdybyś chciał coś zmienić — trzeba odpalić testy fabryki (folder eval/) i udowodnić, że nowy wybór jest lepszy.

Cały stack jednym diagramem

Dlaczego nie piszemy własnego logowania

Zamiast pisać moduł „login + hasło + zapamiętaj sesję + zalogowanie przez Google", używamy gotowego: Better-Auth.

Płatności: Stripe czy Lemon Squeezy

Bramka płatności = firma, która obsługuje przyjmowanie pieniędzy z kart, Apple Pay, Google Pay. Sami nie obsługujemy kart — to są surowe dane finansowe, regulacje i certyfikaty PCI. Wynajmujemy bramkę.

MVP = Minimum Viable Product, czyli „minimalna wersja produktu, którą można pokazać klientowi". Lemon Squeezy jest „Merchant of Record" — to oznacza, że firma sama jest sprzedawcą wobec urzędu skarbowego. Bierze na siebie VAT-MOSS (specjalny VAT na sprzedaż cyfrową w UE), faktury i reklamacje. Dostajesz raz w miesiącu czek netto. Stripe to surowe narzędzie — VAT i faktury robisz sam.

7. Pomocnicy AI — Claude i jego koledzy

W fabryce sztuczna inteligencja pisze kod. Ale jest kilka „smaków" AI, każdy do innego zadania. Trzeba wiedzieć, do czego użyć którego.

Claude Code — główny programista

Claude Code to program firmy Anthropic, działa w terminalu (czarne okienko z komendami). Otwierasz go komendą claude w VS Code (popularny edytor kodu). Pod spodem chodzi model Claude Opus 4.7 — najmocniejszy model AI Anthropic'a, do złożonych zadań.

Tabela modeli — który do czego

200K, 1M = ile tekstu model utrzymuje w pamięci. 200K = ok. 200 tysięcy tokenów = jakieś 150 stron tekstu. 1M = pół miliona tokenów = przeszło 700 stron. Token = kawałek słowa albo całe słowo, którym AI mierzy długość tekstu.

Reguła: jak chcesz przeformatować 20 plików — nie potrzebujesz Opusa. Włącz Sonnet komendą /model sonnet i jest 5 razy taniej, a wynik praktycznie ten sam.

IDE — gdzie piszemy kod

IDE = Integrated Development Environment, czyli „edytor dla programistów". To jak Word, ale do kodu — z kolorowaniem składni, podpowiadaniem, debugowaniem.

• VS Code — główny edytor. Darmowy, od Microsoftu. W nim odpalamy Claude Code w terminalu.
• Cursor — VS Code z wbudowanym AI-pomocnikiem (Composer).
• Windsurf — alternatywa Cursora od Codeium.
• Comet — przeglądarka Perplexity z AI, które klika za Ciebie w panelach (np. żeby coś poprawić w panelu CyberFolks bez wchodzenia tam ręcznie).

Ważna zasada: uruchamiasz VS Code zawsze komendą code -n (n = nowe okno). Nigdy code -r (r = reuse, czyli „użyj istniejącego okna") — bo to zabija sesję Claude w już otwartym oknie.

8. Narzędzia codzienne fabryki

Oprócz pomocników AI mamy w fabryce cztery własne narzędzia — to z nimi zespół pracuje na co dzień. Wszystkie są zainstalowane lokalnie w folderze Nowa apka\flow\.

TRL Store — panel zarządzający fabryką

Aplikacja Node.js z panelem w przeglądarce. To „dyspozytornia" całej fabryki — widzisz tu wszystkie apki na wszystkich poziomach TRL, klikasz „awansuj na wyższy poziom", importujesz nowe apki z dysku, GitHuba albo FTP.

• Gdzie żyje: Nowa apka\flow\apps\01-app-store\
• Adres: http://localhost:3000 (po uruchomieniu)
• Jak uruchomić: dwuklik na START-ALL.bat na pulpicie (otwiera od razu wszystko: TRL Store + screenshot-to-code)
• Co potrafi:
  • Lista wszystkich apek pogrupowana po TRL 1–9
  • Awans apki na wyższy poziom (przesuwa folder na dysku)
  • Importowanie apek z dysku, GitHuba, FTP
  • Podgląd kodu apki w VS Code (przycisk ✏️)
  • Otwarcie apki w screenshot-to-code do poprawiania UI (przycisk 🎨)
  • Chat z szefem kuchni (Brigade de Cuisine — wieloosobowy AI, model Claude Opus 4.6)

Brigade de Cuisine = „brygada kucharska". To architektura, w której kilka modeli AI pracuje razem jak kuchnia w restauracji — szef kuchni (Claude Opus) decyduje, sous chef (Sonnet) wykonuje, commis (Haiku) sprząta. Każdy ma swoje zadanie.

screenshot-to-code — z obrazka na kod

Robisz zrzut ekranu (screenshot) ładnego UI z dowolnej strony albo apki — narzędzie generuje gotowy kod HTML / React / Vue, który ten UI odtwarza. Idealne, jak zobaczysz coś co Ci się podoba i chcesz mieć podobne u siebie.

• Gdzie żyje: Nowa apka\flow\screenshot-to-code-main\
• Adres: http://localhost:5173 (frontend) + :7001 (backend Python)
• Jak uruchomić: START-ALL.bat z pulpitu uruchamia razem z TRL Store
• Co potrafi:
  • Wgrywasz zrzut ekranu → dostajesz kod HTML/React
  • Wpisujesz adres strony → narzędzie samo robi zrzut i konwertuje
  • Zakładka „My Apps" — pokazuje Twoje apki z TRL Store, klik „Popraw UI" → robi zrzut + generuje ulepszony kod
  • Modele AI: Claude (najlepszy do UI), GPT-4 Vision, Gemini

Vision model = model AI, który widzi obrazki (nie tylko czyta tekst). Może opisać co jest na zdjęciu, czytać zrzuty ekranu, generować kod z mockupu UI.

expo-converter — HTML/React → Expo (bez AI)

Mechaniczny konwerter, który bierze gotową apkę HTML albo React i automatycznie owija ją w projekt Expo (czyli daje Ci od ręki wersję na iPhone'a i Androida). Zero kosztów AI — to czysta mechaniczna konwersja.

• Gdzie żyje: Nowa apka\flow\expo-converter\
• Jak uruchomić:

  node converter.js "D:\6 APK APP TRL UP\TRL 5 - Dziala u mnie"
  # Wynik w ./expo-output/

• Co robi:
  • Skanuje folder ze stronami HTML / React
  • Każdą apkę kategoryzuje: HTML / Express → owija w WebView (zawsze działa)
  • React / Vite → konwertuje na natywne komponenty Expo
  • Generuje gotowy projekt Expo, który możesz wrzucić do EAS i wypuścić w sklepach

WebView = komponent w apce mobilnej, który wewnątrz pokazuje stronę HTML — jak okno przeglądarki w środku apki. Najprostszy sposób, żeby stronę zamienić na apkę.

Praktyka TRL 5 → 6: apkę z TRL 5 (działa lokalnie jako strona) możesz natychmiast wypuścić jako apkę mobilną przez expo-converter — bez przepisywania od zera.

UI inspiracje (kreator-ui) — biblioteka komponentów

Folder pełny gotowych klocków do budowy UI: przyciski, czcionki, kolory, szablony ekranów. Kopiujesz to, czego potrzebujesz do swojej apki.

• Gdzie żyje: Nowa apka\flow\UI inspiracje\kreator-ui\
• Co zawiera:
  • buttony/ — gotowe style przycisków (różne wielkości, stany hover, kolory)
  • fonty/ — paczki czcionek z licencjami
  • kolory/ — palety kolorów, gradienty, motywy
  • szablony/ — całe ekrany (logowanie, dashboard, paywall)
  • start.bat — uruchamia mini-serwer z podglądem wszystkich komponentów
• Workflow:
  1. Otwórz UI inspiracje\kreator-ui
  2. Uruchom start.bat
  3. Przeglądasz komponenty w przeglądarce, znajdujesz ten, który chcesz
  4. Kopiujesz kod do swojej apki

Cały dzień pracy — jak narzędzia łączą się ze sobą

Wszystkie cztery narzędzia uruchamiasz jednym dwuklikiem na START-ALL.bat z pulpitu.

10. Serwery i miejsca w internecie — infrastruktura

OVH VPS — silnik produkcji

OVH to francuska firma hostingowa. Wynajmujemy u nich VPS — jeden mały komputer w chmurze, który działa non-stop. Adres IP: 57.131.51.124.

Coolify = darmowy panel zarządzający (typu „one-click deploy"). Robi za Ciebie wszystko, co kiedyś robiło się ręcznie po SSH: ściąga kod z GitHuba, buduje kontener, uruchamia, podpina HTTPS. Traefik = „odźwierny" — przyjmuje ruch z internetu i kieruje go do właściwej apki. Let's Encrypt = darmowa instytucja wydająca certyfikaty HTTPS (kłódkę w przeglądarce).

CyberFolks — hosting na gft.pl

CyberFolks to polska firma hostingowa starszego typu. Trzymamy tam tylko strony statyczne (sam HTML, bez bazy danych). Adres IP: 195.242.116.113. Logujesz się do panelu DirectAdmin pod panel.cyberfolks.pl. Limity: brak SSH, brak Dockera, brak Node.js — czyli tylko zwykłe pliki strony i WordPress.

GitHub TGFTID

Konto Tomasza na GitHubie nazywa się TGFTID. Wszystkie nasze repozytoria są tam. Token (długi sekretny ciąg, daje uprawnienia robotom) i pełne dane są w pliku .TRL-up/credentials.md.

Webhook = automatyczne powiadomienie wysyłane przez serwis (np. GitHub) do innego serwisu (np. Coolify) gdy coś się stanie (np. nowy kod). sslip.io = sprytny darmowy serwis DNS — możesz wpisać dowolny adres IP w nazwę i on go odda jako poddomenę, np. 1-2-3-4.sslip.io = 1.2.3.4.

Hasła — nigdy w kodzie

• Lokalnie: doppler run -- pnpm dev (Doppler wstrzykuje hasła w czasie uruchomienia, do pliku ich nie zapisuje)
• Na serwerze produkcyjnym: Coolify łączy się z Doppler i pobiera hasła do uruchomienia kontenera
• W projekcie jest tylko .env.example (przykład) — z nazwami zmiennych ale BEZ wartości
• Wrzucenie pliku z hasłami na GitHub = natychmiastowa rotacja wszystkich haseł (zmiana na nowe, bo stare są spalone)

Doppler = sejf na hasła i klucze API w chmurze. .env = stary sposób trzymania haseł — plik tekstowy na komputerze. U nas tego unikamy bo łatwo się go przypadkiem wgra na GitHuba.

10. Nie pisz od zera — fork-first

Zasada: zanim cokolwiek napiszesz od zera, sprawdź czy ktoś już tego nie zrobił. W internecie są setki gotowych aplikacji open source (kod publicznie dostępny, za darmo). Często możesz wziąć gotowca, zmienić logo i kolory, dodać 2 funkcje — i mamy 80% pracy zrobionej w 1 dzień.

Robi to za nas pomocnik AI o nazwie SCOUT.

Fork = własna kopia cudzego repozytorium. Możesz ją zmieniać u siebie, oryginał zostaje nienaruszony. Licencja = zasady używania kodu open source. Najpopularniejsze: MIT i Apache 2.0 — można robić cokolwiek (komercyjnie, bez udostępniania zmian); AGPL — można używać, ale jeśli udostępniasz aplikację publicznie, MUSISZ udostępnić swoje zmiany w kodzie.

Złote kopalnie — lista do sprawdzenia

Zasady używania gotowca

1. Trzymaj oryginał jako „upstream" (źródło). Co jakiś czas pobieraj nowości z oryginału do swojej kopii (rebase).
2. Zmieniaj tylko logo, kolory i 2-3 funkcje. Jak będziesz zmieniał wszystko, nie nadążysz z pobieraniem nowości z oryginału.
3. Dostosowuj przez konfigurację i wtyczki, nie przez przepisywanie rdzenia.
4. AGPL — uważaj. Jak hostujesz publicznie, MUSISZ pokazać swój kod. MIT / Apache = robisz co chcesz.
5. Mobile (iPhone, Android) — backend (serwer) bierzemy z gotowca, ale apkę mobilną piszemy w Expo od zera, łącząc się z forkniętym backendem.

11. Wspólne klocki — skills

Skill (po polsku „umiejętność") = wspólny moduł kodu, który dokleja jakąś gotową funkcjonalność do każdej apki w fabryce. To cienki wrapper (opakowanie) na popularną bibliotekę.

Idea: nie piszesz logowania od zera w każdej apce. Importujesz skills/auth i masz logowanie. Pod spodem to Better-Auth, ale Tobie tego nie pokazuje.

Przykład użycia

// gdzieś w ekranie apki:
import { PaywallScreen, useSubscription, openCheckout } from '@skills/payments'

const { isPro } = useSubscription()
if (!isPro) return <PaywallScreen plan="pro" />

return (
  <Button onPress={() => openCheckout({ priceId: 'price_xxx' })}>
    Wykup Pro — 49 PLN miesięcznie
  </Button>
)

Co tu się dzieje? Pytamy „czy ten użytkownik ma Pro?". Jeśli nie — pokazujemy ekran zachęty (PaywallScreen). Jeśli tak — pokazujemy jego funkcje. Przycisk „Wykup Pro" otwiera Stripe Checkout, ale my nic o tym nie wiemy — robi to za nas wrapper.

Reguła: nigdy nie importuj stripe, better-auth ani @sentry/react-native bezpośrednio. Zawsze przez nasz skill. Wyjątek: kod samego skilla (tam musi).

12. Cały proces od pomysłu do produkcji

Tu jest cały pipeline (po polsku „taśma produkcyjna") fabryki — kroki, przez które przechodzi każda nowa apka. Każdy krok ma swojego AI-pomocnika i bramkę kontroli na końcu.

Każdy krok ma deterministyczną bramkę — automat, który mówi „zielono, idź dalej" albo „czerwono, wracaj". Bez zielonej bramki nie idziesz dalej. Bramki są opisane w sekcji 26. Bramki TRL.

13. Krok 0 — buduj.txt (jedyne co piszesz ręcznie)

To jedyny plik, który piszesz ludzką ręką. Resztę generuje fabryka.

Zasady pisania

• Konkretnie. „Pomaga śledzić sesje skupionej pracy metodą Pomodoro" jest lepsze niż „apka do produktywności".
• Persona — wiek + branża. To wpływa na wygląd, ton komunikatów, sposób onboardingu.
• Monetyzacja od początku. Free / freemium / subskrypcja — nie odkładaj „na potem".
• Kolor i charakter — wpływają na wybór biblioteki UI i ikon.

Killer feature = funkcja, dla której ktoś instaluje apkę. Onboarding = pierwsze chwile użytkownika w apce. Streaki = serie nieprzerwanej aktywności (jak w Duolingo). Persona = profil typowego użytkownika.

14. Krok 0.5 — SCOUT, szukamy gotowca

SCOUT bierze manifest i szuka w internecie projektów open source, które już robią to, co planujesz.

Gwiazdki na GitHubie = oznaczenie „lubię to" od programistów. Im więcej, tym popularniejsze. Last commit = data ostatniej zmiany w kodzie. Świeży = aktywny projekt, stary = porzucony.

Decyzja

• ≥60% + licencja OK → TRYB B. Forkujemy, dokładamy upstream remote (źródło), zmieniamy markę i 2-3 funkcje. Mobile piszemy w Expo jako klient SDK forkniętego backendu.
• <60% albo licencja blokuje → TRYB A (greenfield, czyli „od zera"). Stack z konstytucji.

Bramka kroku 0.5: PLAN.md zawiera decyzję A/B z uzasadnieniem. Jeśli B — link do forkniętego repozytorium i lista zmian.

15. Krok 1 — PLANNER pisze plan

PLANNER to AI-pomocnik, który czyta manifest i wynik SCOUT-a. Generuje plik PLAN.md — listę „co trzeba zrobić".

Endpoint = pojedynczy adres w API, np. POST /users = „dodaj użytkownika". Schemat tabeli = projekt tabeli — jakie kolumny, jakie relacje.

Bramka: PLAN.md istnieje, ma wszystkie sekcje, jest zgodny z manifestem.

16. Krok 1.5 — SPECCER, najważniejszy krok

To jest absolutnie najważniejszy moment. Zanim ktokolwiek napisze choć linię kodu — SPECCER pisze testy.

Spec (z angielskiego „specification") = specyfikacja, czyli dokładny opis, co apka MA robić. U nas spec = zestaw testów akceptacyjnych. Testy akceptacyjne = automatyczne klikanie w apce, sprawdzające czy to, co użytkownik chce, faktycznie działa.

Playwright = popularne narzędzie do automatycznego testowania klikania w apce (jak nagrana makro w Excelu, ale dla stron). e2e = end-to-end, czyli „od początku do końca". OpenAPI = sposób opisywania API w pliku YAML, żeby maszyny mogły go zrozumieć. SLO = Service Level Objectives, czyli „cele jakości usługi".

Bramka kroku 1.5

• Testy akceptacyjne parsują się przez Playwright (mogą padać — kodu jeszcze nie ma, OK).
• OpenAPI jest poprawne (sprawdzamy walidatorem).
• SLO są zdefiniowane (czas odpowiedzi, dostępność, budżet błędów).

Spec-driven. Każdy bug w produkcji = najpierw piszemy nowy test, potem fix. Zawsze w tej kolejności.

17. Krok 2 — BOOTSTRAPPER, środowisko

BOOTSTRAPPER tworzy zamknięte środowisko deweloperskie w Dockerze. „Zamknięte" znaczy: identyczne na Twoim laptopie, na laptopie kolegi, na serwerze produkcyjnym.

devcontainer = „kontener deweloperski", środowisko Docker do programowania. pnpm = szybsza wersja narzędzia npm (instalator bibliotek JavaScript). mailhog = fałszywy serwer email do testów (przyjmuje maile, ale nie wysyła nigdzie naprawdę). runbook = instrukcja awaryjna, co robić gdy coś pójdzie źle.

Po co devcontainer

• Środowisko hermetyczne — wszystko w Dockerze.
• Nie instalujesz nic na swoim laptopie (czysty komp).
• Działa identycznie u każdego: Tobie, koledze, na CI, na podglądzie.
• Eliminuje 80% błędów typu „u mnie działa".

Bramka: docker compose up w devcontainerze startuje pustą, czystą bazę. Lokalnie = CI = produkcja.

18. Krok 3 — DB, schemat bazy danych

DB-pomocnik czyta sekcję „tabele" w PLAN.md i generuje schemat Drizzle + migracje.

// backend/src/db/schema.ts
import { pgTable, uuid, text, timestamp } from 'drizzle-orm/pg-core'

export const users = pgTable('users', {
  id:        uuid('id').defaultRandom().primaryKey(),
  email:     text('email').notNull().unique(),
  name:      text('name'),
  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
})

Migracja = zestaw poleceń, które tworzą / zmieniają strukturę bazy. Drizzle = ORM dla TypeScript-a (rozmówca z bazą). UUID = długi unikalny identyfikator (zamiast zwykłej liczby 1, 2, 3).

Zasady

• Każda tabela ma created_at + updated_at (kiedy stworzono, kiedy ostatnio zmieniono).
• Hasła w bazie wyłącznie w postaci hash-a Argon2id (Better-Auth robi to za nas).
• Indeksy na kluczach obcych i polach wyszukiwania (przyspieszenie zapytań).
• Migracje przez pnpm drizzle-kit generate, potem migrate.

Bramka: pnpm drizzle-kit migrate przechodzi bez błędów na lokalnej bazie z devcontainera.

19. Krok 4 — BACKEND, część serwerowa

BACKEND-pomocnik czyta kontrakt API + schemat bazy i pisze endpointy w Hono (frameworku do API).

// backend/src/routes/projects.ts
import { Hono } from 'hono'
import { z } from 'zod'
import { zValidator } from '@hono/zod-validator'

const app = new Hono()

const createSchema = z.object({
  name:        z.string().min(1).max(100),
  description: z.string().optional(),
})

app.post('/', zValidator('json', createSchema), async (c) => {
  const data   = c.req.valid('json')
  const userId = c.get('userId')               // pobiera z Better-Auth
  const project = await projectService.create(userId, data)
  return c.json(project, 201)
})

export default app

Co tu się dzieje? Mamy endpoint POST (dodanie nowego projektu). Najpierw walidujemy dane (zod sprawdza, czy nazwa ma od 1 do 100 znaków). Potem pobieramy ID użytkownika z tokenu (Better-Auth). Potem wołamy serwis, który zapisze projekt do bazy. Na koniec zwracamy 201 (oznacza „utworzono").

Zasady

• Jeden plik per moduł (np. projects.ts, users.ts).
• Logika biznesowa idzie do services/, NIE do routerów.
• Każdy endpoint: walidacja → autoryzacja → serwis → odpowiedź.
• Try/catch + globalna obsługa błędów.
• Ograniczenie liczby prób na /auth/* (Better-Auth ma to wbudowane).

Bramka: pnpm typecheck ✓ · pnpm test:integration ✓ — testy uderzają w PRAWDZIWĄ bazę w devcontainerze, nie w fałszywki.

20. Krok 5 — FRONTEND, ekrany w Expo

FRONTEND-pomocnik generuje ekrany w Expo Router. Pobiera dane przez TanStack Query (typy są automatycznie z OpenAPI), używa skills/.

Splash screen = ekran ładowania z logiem widoczny przy uruchomieniu apki. Hook = funkcja w React, która „zaczepia" coś (np. dane z API). Identyfikator paczki (bundle identifier) = unikalna nazwa apki dla Apple / Google, np. pl.gft.focusflow.

UI / UX — zasady żelazne

• Kontrast tła i tekstu co najmniej 4.5:1 (sprawdzamy automatem axe-core).
• Nigdy szare na szarym.
• Mobile-first (najpierw projektujemy dla telefonu, potem skalujemy do desktopu).
• Każdy ekran ma trzy stany: ładowanie, błąd, pusty — nie tylko „happy path".
• Onboarding, formularze, błędy — zawsze czytelne.

Happy path = ścieżka idealna, gdy wszystko działa. UX = User Experience, czyli „doświadczenie użytkownika".

Bramka: pnpm build (turbo, wszystkie apps) ✓ · pnpm typecheck ✓.

21. Krok 6 — VERIFIER, kontrola jakości

VERIFIER puszcza pełną baterię testów na środowisku podglądowym (Coolify wystawił już URL po push'u brancha).

• spec/acceptance/ — testy Playwright na ŻYWYM URLu, nie tylko lokalnie.
• Test kontraktu API (Schemathesis albo Dredd) — czy backend zachowuje się zgodnie z kontraktem OpenAPI.
• Skanowanie bezpieczeństwa: pnpm audit (czy biblioteki nie mają znanych dziur), Trivy (czy obrazy Docker nie mają dziur).
• Lighthouse na frontendzie — wydajność, dostępność (a11y), SEO.

a11y = accessibility, czyli „dostępność dla osób z niepełnosprawnościami" (kontrast, opisy obrazków, nawigacja klawiaturą). SEO = Search Engine Optimization, czyli „optymalizacja pod wyszukiwarki" (czy Google Cię znajdzie).

Bramka: WSZYSTKIE testy zielone na podglądzie. Jeden czerwony — wracasz do kroku 4 albo 5 z konkretnym błędem. Nie idziesz dalej.

22. Krok 7 — Human Gate, jedyny moment dla człowieka

To jedyny krok w całym pipeline, w którym AI pyta człowieka. Wystawia URL podglądowy, raportuje stan, czeka na decyzję.

Nie pytamy o pierdoły, które AI może rozstrzygnąć sam (nazwa zmiennej, kolor przycisku). Pytamy WYŁĄCZNIE tutaj — czy puszczamy na produkcję?

23. Wystawiamy w internecie — deployment

Wymagania apki, żeby Coolify ją wdrożył

• Dockerfile w głównym katalogu (przepis na kontener)
• Serwer nasłuchuje na 0.0.0.0 (nie localhost!) — bo z zewnątrz kontenera localhost jest „w środku"
• .dockerignore wyklucza node_modules, .env, .git
• Repozytorium publiczne na TGFTID (GitHub App ma już dostęp)

# Dockerfile dla apki Node.js
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

# .dockerignore
node_modules
.env
.git
*.log

# server.js — uwaga na 0.0.0.0!
const PORT = process.env.PORT || 3000;
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Serwer działa na porcie ${PORT}`);
});

Pełna ścieżka wdrożenia

Dodanie poddomeny .gft.pl

1. DNS w panelu CyberFolks (ręcznie, jeden raz):

   Panel · Domeny · gft.pl · Zarządzanie DNS
   Dodaj: A · <poddomena> · 57.131.51.124 · TTL 300

2. FQDN w Coolify (przez API):

   curl -X PATCH "http://57.131.51.124:8000/api/v1/applications/$APP_UUID" \
     -H "Authorization: Bearer $COOLIFY_TOKEN" \
     -d '{"fqdn": "https://<poddomena>.gft.pl"}'

3. Czekasz 5–10 minut, sprawdzasz: curl -I https://<poddomena>.gft.pl → 200 ✓

FQDN = Fully Qualified Domain Name, czyli pełna nazwa domeny (np. trl.gft.pl). DNS A-record = wpis w DNS, który mówi „nazwa X = adres IP Y".

Strony statyczne — CyberFolks

CyberFolks (gft.pl) nie ma SSH ani Dockera. Można tam wgrać tylko zwykłe pliki HTML/CSS/JS przez FTP. Używamy do landingów (stron promujących produkty), blogów, statycznych SPA.

Landing page = strona docelowa, na którą wpadają nowi użytkownicy. SPA = Single Page Application, czyli „aplikacja jednostronicowa" — wszystko działa w przeglądarce bez przeładowywania strony.

# Build i upload
npm run build   # tworzy folder dist/
bash .TRL-up/scripts/cyberfolks-ftp.sh ./dist/ /public_html/moja-apka/

24. Sklepy mobilne — App Store i Google Play

EAS (Expo Application Services) buduje apkę iOS i Android w chmurze — bez Maca, bez Android Studio. Robi też auto-submit, czyli automatyczne wysłanie do sklepu.

Konfiguracja raz na komputerze

npm install -g eas-cli
eas login   # konto: t@gft.pl albo 5gftid@gmail.com

eas.json — wzór konfiguracji

{
  "build": {
    "production": {
      "ios":     { "buildConfiguration": "Release" },
      "android": { "buildType": "app-bundle" }
    }
  },
  "submit": {
    "production": {
      "ios": {
        "appleTeamId": "3X6USLMFNM",
        "ascAppId": "<10-cyfrowy-App-ID-z-App-Store-Connect>"
      },
      "android": {
        "serviceAccountKeyPath": "./google-play-service-account.json",
        "track": "internal"
      }
    }
  }
}

App Store (iPhone) — pierwsze wdrożenie

1. Wejdź na appstoreconnect.apple.com → My Apps → + → New App.
2. Bundle ID: pl.gft.<nazwa> — dokładnie taki sam jak w app.json.
3. Skopiuj 10-cyfrowy „App Store Connect App ID".
4. Wklej do eas.json w polu submit.production.ios.ascAppId.
5. Uruchom: eas build --platform ios --profile production --auto-submit.
6. EAS Cloud Build (15–30 min) → Apple processing (10–30 min) → TestFlight Internal Testing ✓.
7. „Submit for Review" w App Store Connect (1–3 dni recenzji Apple). Po akceptacji „Release" ręcznie.

Bundle ID = unikalny identyfikator paczki (Twoja apka różni się od innych w sklepie tylko tym). TestFlight = aplikacja Apple do testów przedpremierowych. App Review = ludzie z Apple ręcznie przeglądają każdą apkę przed publikacją (sprawdzają czy nie łamie zasad).

Google Play (Android) — service account

1. Play Console → Setup → API access → Create new service account.
2. Google Cloud Console → IAM → Service Accounts → Create → rola „Release Manager".
3. Pobierz JSON klucz → zapisz jako google-play-service-account.json (NIE wgrywaj na GitHub!).
4. Play Console → Users → Invite → email service account → rola Release Manager.
5. Pierwszy plik .aab wgraj ręcznie w Internal Testing (raz).
6. Kolejne razy: eas build --platform android --auto-submit działa już sam.

Service account = „konto robota" — automaty go używają zamiast hasła. .aab = format paczki Android (Android App Bundle).

Tracki Google Play

Zawsze zacznij od internal. Promocja do production przez Play Console (klik) — gdy testy w internal pójdą OK.

Oba sklepy jedną komendą

bash .TRL-up/scripts/deploy-stores-eas.sh all production
# albo prosto:
eas build --platform all --profile production --auto-submit
# 3-4 godziny później: iPhone w TestFlight + Android w Play Internal

25. Pilnujemy co się dzieje — observability

Bez obserwowania nie ma TRL 7+. Produkcji której nie widzisz, nie kontrolujesz.

Stack trace = ślad wykonania programu, gdy się wywrócił — pokazuje gdzie się zepsuło. Breadcrumbs = „okruszki" — historia, co użytkownik klikał przed błędem. Source maps = mapa łącząca skompresowany kod produkcyjny z czytelnym oryginałem. Lejek konwersji = ile osób przechodzi przez kolejne kroki (np. zarejestrowało się, zalogowało, kupiło). Uptime = czas, w którym serwer działa nieprzerwanie. Status page = strona pokazująca, czy serwisy działają (np. status.gft.pl).

Pętla produkcyjna — co się dzieje po wdrożeniu

Issue = zgłoszenie błędu / zadania w GitHubie. Alert fatigue = „zmęczenie alarmami" — gdy alarmów jest za dużo, ludzie przestają je czytać. Ustawiaj alerty TYLKO dla rzeczy krytycznych (P1).

26. Jak zarabiamy — Stripe vs Lemon Squeezy

Każda apka od pierwszego dnia ma podpiętą obsługę płatności. To nie jest „dopiszemy potem" — to skill, który podpina się jak logowanie.

B2B = Business to Business, czyli „firma sprzedaje firmie". B2C = Business to Consumer, „firma sprzedaje osobie prywatnej". VAT MOSS = specjalny system VAT dla sprzedaży cyfrowej w UE — naliczasz VAT klienta z jego kraju (a nie swojego). Webhook = automatyczne powiadomienie wysyłane do Twojej apki, gdy coś się stanie u dostawcy płatności (np. „klient zapłacił").

Wrapper w skill

import { PaywallScreen, useSubscription, openCheckout } from '@skills/payments'

const { isPro, isLoading } = useSubscription()
if (!isPro) return <PaywallScreen plan="pro" />
return <ProFeaturesScreen />

Wrapper ukrywa szczegóły Stripe lub LS. Jak zechcesz przesiąść się ze Stripe na LS, podmieniasz wrapper. Reszta kodu nic nie wie.

27. Bramki TRL — czeklisty przeskoków

Każda bramka to automat. Nie idziesz dalej, dopóki automat nie jest zielony. Bez wyjątków, bez „to tylko ten raz".

28. Co jak się zatnie 3 razy na tym samym

Nie panikuj. Nie pytaj człowieka od razu. Przejdź te kroki po kolei:

1. Sprawdź bramkę. Czy test/check naprawdę definiuje co jest „skończone"? Jeśli nie — dopisz nowy test do spec/. To pewnie ten brak.
2. Sprawdź devcontainer. Czy środowisko jest hermetyczne? Czy lokalnie ≠ podgląd ≠ produkcja? Jeśli tak — napraw devcontainer, nie omijaj problemu.
3. Sprawdź sekrety. Czy Doppler ma wszystkie klucze? Czy Coolify czyta z Doppler poprawnie? doppler secrets.
4. Sprawdź runbook. Czy ten problem jest w infra/runbooks/? Jeśli tak — wykonaj. Jeśli nie — dopisz po naprawie.
5. Dopisz test w eval. Jeśli problem powtarza się w różnych projektach → dodaj do eval/tasks/, żeby fabryka się tego nauczyła.
6. Dopiero teraz idź do człowieka. I to konkretem: „utknąłem na X, próbowałem A/B/C, oto logi".

29. Sprawdź siebie — 10 pytań

Po przeczytaniu materiału powinieneś umieć odpowiedzieć:

1. Czym różni się Coolify od CyberFolks i kiedy używasz którego?
2. Gdzie trzymasz hasła i klucze (lokalnie, w CI, w produkcji)?
3. Co znaczy TRL 6? Jaka jest bramka wyjścia z TRL 6?
4. Kiedy używasz modelu Opus, kiedy Sonnet, kiedy Haiku?
5. Fork-first — kiedy TRYB B (fork) zamiast TRYB A (od zera)?
6. Dlaczego nie piszemy własnego JWT, tylko bierzemy Better-Auth?
7. Co to Neon branches per PR i po co to jest?
8. Jak publikuje się apkę do App Store od zera?
9. Stripe vs Lemon Squeezy — kiedy który?
10. Gdzie trafia błąd z produkcji i co się z nim dzieje?

Klucz do odpowiedzi

1. Coolify = apki Node/Docker, środowiska podglądowe, SSH, API. CyberFolks = statyczne pliki HTML, WordPress, PHP. Apkę z bazą = Coolify. Stronę landing = CyberFolks.
2. Lokalnie: Doppler. CI: zmienna DOPPLER_TOKEN + Doppler. Produkcja: integracja Coolify ↔ Doppler. Nigdy .env w repo.
3. TRL 6 = środowisko podglądowe działa. Bramka: URL podglądowy się otwiera + testy e2e Playwright zielone na podglądzie.
4. Opus = architektura, debugowanie, refaktoryzacja. Sonnet = drobne edycje, dokumentacja. Haiku = operacje masowe (100+ plików).
5. Gdy SCOUT znajdzie OSS pokrywający ≥60% wymagań i licencja pasuje (MIT/Apache zawsze, AGPL gdy publiczny hosting jest OK).
6. Better-Auth daje Argon2id + OAuth + MFA + ograniczenie prób z pudełka. Własny JWT = 2 tygodnie + dziury.
7. Każdy PR ma własną kopię bazy Postgres (Neon branch). Zniszczyłeś migrację? Dropnij branch, zrób nowy. Zero ryzyka dla produkcji.
8. (1) Stwórz apkę w App Store Connect z bundleId. (2) Skopiuj 10-cyfrowy ascAppId do eas.json. (3) eas build --platform ios --auto-submit. (4) Po recenzji Apple klikasz „Release".
9. Stripe = B2B z NIP-em, USA. Lemon Squeezy = B2C w UE, Merchant of Record, MVP.
10. Sentry łapie błąd → tworzy issue w GitHubie → AI czyta → pisze fix + test → PR → środowisko podglądowe → human merge → wdrożenie → Sentry obserwuje 5 min → issue zamknięte.

30. Cheatsheet — komendy do skopiowania

GitHub push (nowe repo)

cd <folder-apki>
git init && git add -A && git commit -m "init"
gh auth login --with-token <<< "$GITHUB_TOKEN"
gh repo create TGFTID/<nazwa> --public --source=. --push

Wdrożenie na Coolify (OVH)

bash .TRL-up/scripts/deploy-app.sh <nazwa> TGFTID/<repo> 3000

# Dodaj klucze API z .TRL-up
bash .TRL-up/scripts/add-env-to-coolify.sh <APP_UUID>

Upload na CyberFolks (gft.pl)

npm run build
bash .TRL-up/scripts/cyberfolks-ftp.sh ./dist/ /public_html/<subfolder>/

Build i wysyłka do sklepów

# Oba sklepy naraz:
bash .TRL-up/scripts/deploy-stores-eas.sh all production
# Albo bezpośrednio:
eas build --platform all --profile production --auto-submit
# Status:
eas build:list

SSH na VPS

ssh ubuntu@57.131.51.124
# hasło w .TRL-up/credentials.md

Coolify API — szybkie operacje

COOLIFY_TOKEN="..."  # z .TRL-up/credentials.md
BASE="http://57.131.51.124:8000/api/v1"

# Lista aplikacji
curl -s "$BASE/applications" -H "Authorization: Bearer $COOLIFY_TOKEN" \
  | jq '.[] | {name, uuid, fqdn, status}'

# Ponowne wdrożenie
curl -X POST "$BASE/applications/$APP_UUID/restart" \
  -H "Authorization: Bearer $COOLIFY_TOKEN"

# Dodaj zmienną środowiskową
curl -X POST "$BASE/applications/$APP_UUID/envs" \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"MOJ_KLUCZ","value":"wartosc","is_build_time":false}'

Doppler — sekrety

# Lokalnie odpal apkę z hasłami z Doppler:
doppler run -- pnpm dev
# Lista sekretów:
doppler secrets
# Ustaw nowy:
doppler secrets set MOJ_KLUCZ=wartosc

Materiał szkoleniowy · Fabryka aplikacji TRL · GFT

Pytania: t@gft.pl

Materiały źródłowe: .TRL-up/ + ovh/

Strona: trl.gft.pl