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 projektuArchitektura i technikalia projektuStack technologiczny i struktura projektuGłówny README.md ma sztandarową tabelę stacku (PHP/Laravel, Inertia, React/TypeScript/Vite, Tailwind, SQLite, Pest/Vitest). Ten przewodnik schodzi o poziom… — 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 backenduArchitektura i technikalia projektuWarstwowa architektura backenduController → Service → Repository, bez wyjątków i bez skrótów — kontroler nigdy nie buduje zapytania Eloquent, a repozytorium nigdy nie zawiera logiki bizn… — 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 designArchitektura i technikalia projektuArchitektura frontendu i atomic designBrowser requests /projects/5 │ ▼ routes/web.php → ProjectController::show() - Inertia::render('Projects/Show', [ ...props ]) │ ▼ Inertia (server) serialize… — 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 deploymentArchitektura i technikalia projektuDocker, Doppler i deploymentGłówny README.md już przeprowadza przez używanie setupu Docker/Doppler od początku do końca (komendy, w jakim jesteś trybie, rozwiązywanie MissingAppKeyExc… — 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-celeArchitektura i technikalia projektuZakres i nie-celeRzeczy, które na pierwszy rzut oka wyglądają, jakby mogły brakować, były na wpół zbudowane albo warte "naprawienia", ale w rzeczywistości są celowe — przec… — 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.