Architektura i technikalia projektu

Każda inna kategoria w documentation/ to przewodnik krok po kroku "jak rozszerzyć X" dla jednego konkretnego podsystemu. Ta kategoria jest inna z natury: to mapa całego projektu — stack, cykl życia żądania/odpowiedzi, zasady warstwowania, lokalne środowisko deweloperskie oraz to, co celowo nie jest jeszcze zbudowane — przeczytaj to najpierw, jeśli jesteś nowy w tym kodzie, przed jakąkolwiek inną kategorią.

Duża część tej treści już istnieje w głównym katalogu repo — top-level README.md to naprawdę dogłębny dokument onboardingowy (tabela stacku, pełne omówienie Docker/Doppler, kroki deploymentu, mapa struktury projektu, lista konwencji), a CLAUDE.md to skondensowana referencja, jaką sam Claude Code ładuje w każdej sesji. Ta kategoria nie zastępuje żadnego z nich — schodzi o poziom głębiej w konkretne mechanizmy, które te dwa dokumenty celowo trzymają zwięźle (dokładny cykl życia żądania, per-serwisowe okablowanie Docker Compose, pełna lista zależności i po co jest każda z nich, jawne nie-cele), i odsyła z powrotem do obu zamiast je powtarzać.

Przewodniki, w kolejności, w jakiej faktycznie będziesz ich potrzebować

1. Stack technologiczny i struktura projektu — każda prawdziwa zależność (nie tylko te sztandarowe) i do czego faktycznie służy, plus głębsze przejście po mapie katalogów niż tabela podsumowująca w głównym README.
2. Warstwowa architektura backendu — Controller → Service → Repository, prześledzone przez jedno prawdziwe żądanie od początku do końca, oraz checklista do dodania zupełnie nowej domeny w tym samym kształcie.
3. Architektura frontendu i atomic design — mechanizm rozstrzygania stron Inertii, stos providerów, pod którym montuje się każda strona, trzy poziomy atomic design z faktyczną zasadą, co gdzie należy, oraz podział na współdzielone propy/lokalny stan.
4. Docker, Doppler i deployment — co faktycznie robi każdy serwis Compose, dwuetapowy Dockerfile, dokładnie jak wykrywany jest tryb Doppler-linked vs. fallback .env, oraz checklista deploymentu produkcyjnego.
5. Zakres i nie-cele — czego Orbit celowo jeszcze nie robi (prawdziwe REST API, globalna rola admina, większość zakładek ustawień Workspace, laravel/sanctum mimo bycia zależnością) i dlaczego, żebyś nie szukał czegoś, czego nie ma, ani przypadkiem nie cofnął celowej decyzji.

Architektura w jednym akapicie

Orbit to jeden kod Laravel + Inertia.js + React bez osobnej warstwy API — każda strona jest renderowana po stronie serwera jako odpowiedź Inertii niosąca prawdziwe propy w kształcie modeli Eloquent, a te same modele nigdy nie dostają drugiej, ręcznie utrzymywanej reprezentacji JSON API, jakiej potrzebowałby oddzielony SPA. Backend to ścisły trzywarstwowy stack (Controller → Service → Repository — zobacz przewodnik 2); frontend to atomic design (Atoms → Molecules → Organisms → Pages — zobacz przewodnik 3) owinięty w stały stos providerów (ThemeProvider → AccentProvider → ModalProvider → AlertProvider → ShortcutProvider), pod którym montuje się identycznie każda strona. Lokalny development działa albo natywnie (PHP + Node bezpośrednio), albo w Dockerze, z opcjonalnym podłączeniem Dopplera dostarczającym sekrety do procesu Docker Compose zamiast zwykłego pliku .env — zobacz przewodnik 4 po dokładnie to, jak działa ta detekcja.