3-tasoinen dokumentaatio
Brownfield-kehityksessä dokumentaatio on navigointikartta. Ilman sitä AI ja kehittäjät eksyvät suureen koodikantaan. Tämä oppitunti opettaa 3-tasoisen dokumentaatiorakenteen, joka tekee koodikannasta navigoitavan.
Miksi 3 tasoa?
3-tasoinen dokumentaatio
3-tasoinen dokumentaatio jakaa tiedon kolmeen abstraktiotasoon: T1 (Arkkitehtuuri) antaa kokonaiskuvan, T2 (Alajärjestelmät) kuvaa kunkin osan rajapinnat ja tietovirran, T3 (Moduulit) sisältää toteutustason yksityiskohdat ja viittaukset lähdekoodiin. Jokainen taso viittaa ylös, alas ja sivulle — luoden navigoitavan verkon.
Kolme tasoa
Taso 1: Arkkitehtuuri
Sijainti: docs/
Sisältö: Tarkoitus, teknologiapino, tietomalli, järjestelmäkaavio
Navigointi: → Taso 2 alajärjestelmäviittausten kautta
# NextPath AI — Arkkitehtuuri
## Tarkoitus
AI-oppimisalusta, joka tarjoaa kiltapohjaisia oppimispolkuja.
## Teknologiapino
- Frontend: Next.js 15, React, Tailwind CSS
- Backend: Supabase (PostgreSQL, Auth, Storage)
- AI: Gemini API (coach, exercises)
## Alajärjestelmät
- [Auth](/docs/subsystems/auth/) — Kirjautuminen ja käyttöoikeudet
- [Guilds](/docs/subsystems/guilds/) — Kiltojen hallinta
- [Lessons](/docs/subsystems/lessons/) — Oppisisältö
- [Progress](/docs/subsystems/progress/) — Edistymisen seuranta
## Tietomalli
guilds → lessons → slides
guilds → guild_memberships → profiles
profiles → course_progress → lessonsTaso 2: Alajärjestelmät
Sijainti: docs/subsystems/<nimi>/
Sisältö: Rajapinnat, tietovirta, suunnittelumallit
Navigointi: ↑ T1, ↓ T3, → muut alajärjestelmät
# Auth-alajärjestelmä
## Yleiskatsaus
Hoitaa käyttäjän tunnistautumisen ja käyttöoikeuksien hallinnan.
Ks. kokonaisarkkitehtuuri: [T1 Architecture](/docs/architecture.md)
## Rajapinnat
- Supabase Auth (Magic Link, OAuth)
- verifyGuildAccess() — killan pääsyoikeustarkistus
- RLS-politiikat — rivitason turvallisuus
## Tietovirta
1. Käyttäjä kirjautuu → Supabase Auth
2. Session tallennetaan → Cookie
3. Server Component lukee session → createClient()
4. RLS-politiikat suodattavat tietokantatulokset
## Moduulit
- [Server Client](/docs/subsystems/auth/modules/server-client.md)
- [Guild Access](/docs/subsystems/auth/modules/guild-access.md)
## Riippuvuudet
- Käyttää: Supabase Auth SDK
- Käytetään: Guilds, Lessons, ProgressTaso 3: Moduulit
Sijainti: docs/subsystems/<nimi>/modules/
Sisältö: Toteutusyksityiskohdat, @file-viittaukset lähdekoodiin
Navigointi: ↑ T2, → lähdekoodi
# Server Client -moduuli
## Tiedostot
- @file lib/supabase/server.ts — Supabase-clientin luonti
- @file lib/supabase/middleware.ts — Middleware-integraatio
## Toiminto
Luo Supabase-clientin server-komponenteille ja API-routeille.
## Funktiot
### createClient()
- Lukee session cookiesta
- Palauttaa autentikoiden Supabase-clientin
- Käytetään jokaisessa Server Componentissa
### verifyGuildAccess(slug, options?)
- Tarkistaa pääsyoikeuden kiltaan
- options.requireRole: vaatii tietyn roolin
- Palauttaa: { guild, profile, membership }
## Yhteys ylätasoon
Ks. [Auth-alajärjestelmä](/docs/subsystems/auth/)Pro-vinkki
@file-viittaukset T3-tasolla ovat kriittisiä. Ne luovat suoran linkin dokumentaatiosta lähdekoodiin. Kun AI lukee T3-dokumentin, se tietää täsmälleen mitkä tiedostot pitää avata.
content-plan.md — Indeksi
content-plan.md on dokumentaation indeksi — ensimmäinen tiedosto jonka AI lukee.
# Documentation Index
| # | Moduuli / Alue | Taso | Status | Polku | Prioriteetti |
|---|----------------|------|--------|-------|--------------|
| 1 | Architecture | T1 | Done | docs/architecture.md | Critical |
| 2 | Data Model | T1 | Not Started | docs/datamodel.md | Critical |
| 3 | Auth | T2 | In Progress | docs/subsystems/auth/ | High |
| 4 | Server Client | T3 | Done | docs/subsystems/auth/modules/server-client.md | Medium |
| 5 | Guilds | T2 | Not Started | docs/subsystems/guilds/ | High |
Generation order: T1 ensin → Core T2 → Feature T2 → T3 viimeisenäNavigointistrategiat
AI navigoi dokumentaatiota kolmella tavalla:
1. Ylhäältä alas (Top-Down)
Polku: T1 → T2 → T3 → Koodi Käyttö: Kokonaisymmärryksen rakentaminen, suunnittelu
2. Ominaisuuskohtainen (Feature-Wise)
Polku: content-plan → speksi → relevantit alajärjestelmät → moduulit Käyttö: Ominaisuuden toteutus
3. Pakettikohtainen (Package-Wise)
Polku: common → server → client Käyttö: Tietovirran debuggaus
Ristikkäisnavigointi
3-tasoisen dokumentaation voima on ristikkäisnavigoinnissa: jokainen dokumentti viittaa ylös (ylätaso), alas (alataso) ja sivulle (riippuvuudet). Tämä mahdollistaa minkä tahansa dokumentin löytämisen mistä tahansa aloituspisteestä.
Dokumentaation generointi AI:lla
AI on erinomainen dokumentaation generoinnissa olemassa olevasta koodista:
- Anna AI:lle content-plan.md — se tietää mitä puuttuu
- Skannaa tiedostojärjestelmä — AI kartoittaa moduulit
- Generoi T1 ensin — kokonaiskuva
- Sitten T2 — alajärjestelmät
- Lopuksi T3 — moduulitason yksityiskohdat
Miksi 3-tasoinen dokumentaatio on tehokkaampi kuin yksi iso dokumentti?
Luo 3-tasoinen dokumentaatio
Valitse projekti ja luo sille content-plan.md + T1-arkkitehtuuridokumentti. 1) Tunnista 3–5 alajärjestelmää, 2) Kirjoita content-plan.md jossa jokainen rivi viittaa T1/T2/T3-dokumenttiin, 3) Generoi T1 arkkitehtuuridokumentti. Bonus: pyydä AI:ta generoimaan yksi T2-dokumentti.
Yhteenveto
- 3-tasoinen dokumentaatio: T1 (arkkitehtuuri) → T2 (alajärjestelmät) → T3 (moduulit)
content-plan.mdon indeksi jonka AI lukee ensimmäisenä- Ristikkäisviittaukset mahdollistavat navigoinnin mihin tahansa suuntaan
- @file-viittaukset T3-tasolla linkittävät dokumentaation suoraan koodiin
- Seuraavaksi opimme perustellun speksilähtöisen kehityksen