Arkkitehtuurin tavoitteet¶

Tämä dokumentti kuvaa ne lähtökohdat, tarpeet ja tekniset vaatimukset, joiden pohjalta RepoStage-ekosysteemi on rakennettu. RepoStage ei ole pelkkä dokumentaatiosivusto, vaan vastaus tarpeeseen hallita sirpaloitunutta projektitietoa yhtenäisellä tavalla.

Lähtökohdat ja tarve¶

Henkilökohtaisen projektisalkun kasvaessa syntyy tarve hallita kokonaisuutta, joka on hajautettu useisiin eri palveluihin (GitHub, GitLab). Ilman keskitettyä arkkitehtuuria projektit muuttuvat vaikeasti ylläpidettäviksi saarekkeiksi.

RepoStagen perustehtävä:

• Ratkaista sirpaleisuus: Tuoda eri alustojen projektit yhteen näkymään.
• Vähentää manuaalista työtä: Automatisoida tietojen päivitys koodin ja dokumentaation välillä.
• Todentaa osaaminen: Näyttää tekninen kyvykkyys arkkitehtuurin, automaation ja dokumentoinnin kautta.

Arkkitehtuuriset vaatimukset¶

Suunnittelua ohjaavat tiukat vaatimukset, jotka varmistavat järjestelmän elinkaaren:

1. Automaatio-ensisijaisuus (Automation First) Tiedon (nimet, kuvaukset, kielet) on virrattava rajapinnoista ilman manuaalista editointia.

2. Skaalautuvuus Uuden projektin lisäämisen on oltava "zero-effort" – portaalin on tunnistettava uusi sisältö automaattisesti nimeämisstandardien perusteella.

3. Yhtenäinen visualisointi Kaikkien projektien on näyttävä osana samaa ekosysteemiä, riippumatta siitä, missä niiden lähdekoodi fyysisesti sijaitsee.

4. Luotettava julkaisuprosessi Kehityksen (Dev) ja tuotannon (Main) on oltava erillään, jotta automaatioskriptien muutokset voidaan validoida ennen julkaisua.

Ratkaisun rakenne (Kokonaisrakenne)¶

Vaatimukset täytetään kolmivaiheisella rakenteella, jossa frontend-kerros rakentuu täysin automatisoidusti:

1) Älykäs pääprojekti (Orchestrator)¶

• Rooli: Ohjaa tiedonhakua ja generoi portaalin käyttöliittymän.
• Työkalut: MkDocs Material ja räätälöidyt Python-automaatiot, jotka tuottavat frontend-näkymän dynaamisesti kerätyn datan pohjalta.

2) Standardisoidut aliprojektit (Data Sources)¶

• Rooli: Toimivat itsenäisinä kehitysympäristöinä.
• Vaatimus: Sisältävät README.md-tiedoston, joka noudattaa sovittua rakennetta kuvauksen poimimista varten.

3) Automaatiokerros (CI/CD & Logic)¶

• Rooli: Yhdistää projektit portaaliksi.
• Logiikka: Regex-pohjainen kategorisointi ja API-integraatiot.

Looginen kategorisointi¶

Jotta laajennettavuus toteutuu, projektit luokitellaan niiden nimeämisen (prefix-) mukaan. Tarkemmat tekniset määritykset löytyvät Standards-osion dokumentista: Nimeäminen-luokittelu.

• Services – Taustajärjestelmät ja API-toteutukset.
• Frontends – Web- ja mobiilikäyttöliittymät, mkdocs automaatio.
• Tools & Infra – Skriptit, automaatiot ja IaC-mallit.
• Experiments – Teknologiset kokeilut ja oppiminen.

Yhteenveto ratkaisusta¶

RepoStage-arkkitehtuuri vastaa tarpeeseen luomalla kevyen mutta älykkään kerroksen hajallaan olevan koodin päälle. Se ei rajoita kehitystä aliprojekteissa, mutta pakottaa ne osaksi laadukasta ja yhtenäistä kokonaiskuvaa. Käyttöliittymä (Frontend) on tämän automaatioketjun lopputuote, joka pidetään ajan tasalla ilman manuaalista työtä.

Dokumentin tila: Luonnos — Pvm: 13.01.2026