FlowSpace Docs
Main Site Hlavná stránka
[ 05 ] CONTRIBUTING PRISPIEVANIE

For people who want to extend FlowSpace. Pre tých, čo chcú FlowSpace rozšíriť.

Architecture, key concepts, fork rules and the contribution flow — so you can confidently add lessons, simulations, pages or entire new features. Architektúra, kľúčové koncepty, pravidlá forkov a postup prispievania — aby si vedel pridávať lekcie, simulácie, stránky alebo celé nové funkcie.

[ 5.1 ]Architecture in one minuteArchitektúra za minútu

Three clean layers talk over HTTP / SQL. Each layer has a single responsibility. Tri čisté vrstvy komunikujú cez HTTP / SQL. Každá vrstva má jednu zodpovednosť.

  • Frontend (frontend/) — React 18 + TypeScript + Vite + React Flow. Talks to backend through a small typed API client.Frontend (frontend/) — React 18 + TypeScript + Vite + React Flow. S backendom komunikuje cez malý typovaný API klient.
  • Backend (backend/) — FastAPI, SQLAlchemy 2, Alembic. Each domain has its own router, service and schemas.Backend (backend/) — FastAPI, SQLAlchemy 2, Alembic. Každá doména má vlastný router, service a schémy.
  • Database — PostgreSQL 17. Schema versioned with Alembic; never edit by hand in production.Databáza — PostgreSQL 17. Schéma verzovaná Alembic-om; v produkcii nikdy neupravuj ručne.

[ 5.2 ]Important things to knowDôležité veci, ktoré treba vedieť

[ K01 ]

Auth & JWTAuth a JWT

Email/password + JWT. OAuth buttons appear only when provider keys are set in .env.Email/heslo + JWT. OAuth tlačidlá sa zjavia len pri nastavených kľúčoch v .env.

[ K02 ]

Seed dataSeed dáta

Initial lessons/tasks/systems are seeded automatically on first start. Edit seeders to change starter content.Prvotné lekcie/úlohy/systémy sa nasejú automaticky pri prvom štarte. Pre zmenu počiatočného obsahu uprav seedery.

[ K03 ]

SimulationsSimulácie

Runs are deterministic — the backend stores every run so charts are reproducible per user.Behy sú deterministické — backend ukladá každý beh, takže grafy sa dajú reprodukovať pre každého používateľa.

[ K04 ]

MigrationsMigrácie

Every schema change = new Alembic revision. Autogenerate is a starting point, always review the diff.Každá zmena schémy = nová Alembic revízia. Autogenerate je začiatok, vždy prekontroluj diff.

[ K05 ]

i18ni18n

The UI, docs and site ship with EN/SK. Every new user-facing string must have both languages.UI, dokumentácia aj web sú v EN/SK. Každý nový text pre používateľa musí byť v oboch jazykoch.

[ K06 ]

FilesSúbory

User files live in FILES_DIR inside the container and a host folder (FILES_HOST_DIR) in Docker.Súbory používateľov žijú v FILES_DIR v kontajneri a v hostiteľskom priečinku (FILES_HOST_DIR) v Dockeri.

[ 5.3 ]Fork rulesPravidlá forkov

  1. You are free to fork and use FlowSpace in your own course or project — keep a visible credit and link back to the original repository.Môžeš si FlowSpace forknúť a použiť vo svojom predmete alebo projekte — zachovaj viditeľné poďakovanie a odkaz na pôvodný repozitár.
  2. Do not publish forks with committed secrets (.env, API keys, DB dumps with real users).Nezverejňuj forky s commitnutými tajomstvami (.env, API kľúče, DB dumpy s reálnymi používateľmi).
  3. Keep the same folder structure on top level. If you add new top-level folders, document them in your fork's README.Zachovaj rovnakú štruktúru na najvyššej úrovni. Ak pridáš nové top-level priečinky, zdokumentuj ich v README svojho forku.
  4. If you change the data model, add an Alembic migration — do not ship raw SQL patches.Ak meníš dátový model, pridaj Alembic migráciu — neposielaj surové SQL patche.
  5. Respect the EN/SK policy — both languages or neither.Rešpektuj EN/SK politiku — oba jazyky alebo žiadny.
  6. Never rename core environment variables without updating .env.example, docs and migration notes.Nikdy nepremenúvaj jadrové environment premenné bez aktualizácie .env.example, dokumentácie a migračných poznámok.

[ 5.4 ]Contribution flowPostup prispievania

  1. STEP 01

    Fork & branchFork a branch

    Create a focused branch from main. Small PRs land faster than big ones.Vytvor fokusovanú vetvu z main. Malé PR-ky prechádzajú rýchlejšie než veľké.

    git checkout -b feat/short-name
  2. STEP 02

    Code + tests togetherKód a testy spolu

    Every behavior change needs a test. Put backend tests in test/backend. Keep tests isolated and fast.Každá zmena správania potrebuje test. Backend testy daj do test/backend. Testy nech sú izolované a rýchle.

    pytest -q test/backend
  3. STEP 03

    Migrate if schema changesMigruj pri zmene schémy

    Generate a migration and review it carefully before committing.Vygeneruj migráciu a pred commitom ju dôkladne prekontroluj.

    alembic -c backend/alembic.ini revision --autogenerate -m "short_summary"
  4. STEP 04

    Update docsAktualizuj dokumentáciu

    If behavior, config or UX changes, update pages in docs/. Docs are part of definition of done.Ak meníš správanie, konfiguráciu alebo UX, aktualizuj stránky v docs/. Dokumentácia je súčasťou „definition of done“.

  5. STEP 05

    Commit styleŠtýl commit-u

    Short imperative subject (< 72 chars). Optional body explains why, not what.Krátky imperatívny subject (< 72 znakov). Voliteľné telo vysvetľuje prečo, nie čo.

    feat(sim): deterministic replay for run history

Make runs reproducible per user by storing step inputs.
  6. STEP 06

    Open a Pull RequestOtvor Pull Request

    Describe what changes and why. Mention release impact, new env vars, new migrations.Popíš, čo sa mení a prečo. Uveď dopad na release, nové env premenné, nové migrácie.

[ 5.5 ]Code styleŠtýl kódu

  • Python — type hints, PEP 8, prefer explicit over clever. Services don't import routers.Python — type hints, PEP 8, radšej explicitné než chytré. Services neimportujú routery.
  • TypeScript — strict mode, no any in new code, colocate component + styles + tests.TypeScript — strict mode, v novom kóde žiadne any, komponent + štýly + testy drž spolu.
  • Commits — one logical change per commit. No mixed refactor + feature.Commity — jedna logická zmena na commit. Nemiešaj refactor a feature.

[ 5.6 ]Reporting issuesHlásenie chýb

  • Steps to reproduce, expected vs. actual behavior, relevant log lines.Kroky na zopakovanie, očakávané vs. skutočné správanie, relevantné logy.
  • Environment info: OS, Docker version, browser.Info o prostredí: OS, verzia Dockeru, prehliadač.
  • For security issues use private contact, do not open a public issue.Pre bezpečnostné chyby použi privátny kontakt, nezakladaj verejný issue.
© 2026 FlowSpace / ContributingPrispievanie