Dan 0: Struktura projekta Učitelj Vasa

Vreme potrebno: 60 – 120 minuta

Gde je Učitelj Vasa danas?

Učitelj Vasa još uvek ne postoji, ali postavljamo temelje za njegovo rođenje. Instalirali smo Python i PyCharm, kreiran je GitHub nalog i repository “ucitelj-vasa” – našu radioniku i digitalni dom su spremni. Danas kreiramo kostur projekta – strukturu foldera u koju ćemo narednih 28 dana ulivati život našem AI asistentu.

Cilj današnje lekcije

Danas ćeš kreirati profesionalnu strukturu projekta sa svim potrebnim folderima, naučićeš šta su Python paketi i zašto su važni, i napravićeš osnovne konfiguracione fajlove. Nakon ove lekcije, projekat Učitelj Vasa će imati čvrste temelje na kojima ćemo graditi AI asistenta.

Predznanja

Instaliran Python 3.13+ (Dan -3)
Instaliran i podešen PyCharm unified edition (Dan -2)
Kreiran GitHub nalog i repository “ucitelj-vasa” (Dan -1)
Repository je povezan sa PyCharm-om
Osnovno razumevanje šta su fajlovi i folderi

Glavni sadržaj

Zašto je struktura projekta kao temelj kuće?

Zamisli da gradiš kuću bez plana – samo nasumično postavljaš cigle. Šta bi se desilo? Kuća bi se srušila ili bi bila neupotrebljiva. Isto važi i za programiranje. Dobra struktura projekta je kao dobar arhitektonski plan – omogućava da projekat raste bez haosa, da lako pronađeš kod koji tražiš, i da drugi programeri mogu da razumeju tvoj rad.

📚 NIVO 1 – Osnovno objašnjenje

Struktura projekta je kao sređen ormar – svaka stvar ima svoje mesto. Majice u jednoj fioci, čarape u drugoj. U programiranju, svaki tip koda ima svoj folder. Ovo nije samo zbog lepote – kada projekat poraste na hiljade linija koda, bez dobre organizacije bi bio potpuni haos. Danas pravimo “fioke” za naš kod.

🚀 NIVO 2 – Dublje razumevanje

Profesionalni Python projekti koriste standardizovane strukture koje su evoluirale kroz godine. Dobra struktura omogućava skalabilnost (projekat može da raste), maintainability (lako održavanje), i kolaboraciju (drugi razumeju organizaciju). Struktura koju danas pravimo prati moderne Python best practices i priprema nas za rad sa naprednim alatima kasnije.

💡 PRO TIP: Ako želiš da proveriš koliko ti je projekat „uredan”, pokreni komandu tree -I "__pycache__|venv|\.git" u terminalu. Dobiješ brzu „mapu” svega što si napravio, a svaka nova „cigla” (fajl) odmah se vidi van mesta. Navikni se da ovo radiš posle većih izmena—poput arhitekte koji svakog dana pogleda plan kuće pre nego što nastavi gradnju.

🔍 UVID: Ova organizacija nije samo “dobra praksa”, već tvoj prvi susret sa jednim od najvažnijih principa softverskog inženjeringa: Separation of Concerns (SoC). Baš kao što u kuhinji ne držiš alat iz garaže, u kodu ne mešaš logiku za komunikaciju sa AI servisima (ai_services) sa logikom za prikazivanje web stranica (web_api). Razdvajanjem “briga”, postižeš da je svaki deo sistema odgovoran za samo jedan posao.

Python paketi – magija init.py fajlova

Python folder postaje “paket” kada sadrži specijalni fajl nazvan __init__.py. Ovaj fajl može biti potpuno prazan, ali njegova sama prisutnost govori Python-u: “Hej, ovo nije običan folder, ovo je paket sa Python kodom!”

📚 NIVO 1 – Jednostavno objašnjenje

Predstavi da imaš kutiju sa igračkama. Da bi Python znao da je to posebna kutija sa njegovim “igračkama” (modulima), moraš staviti posebnu oznaku – __init__.py fajl. Bez te oznake, Python misli da je to samo obična kutija i neće moći da koristi igračke iz nje. Ovaj fajl je kao putokaz koji govori: “Ovde ima Python koda!”

🚀 NIVO 2 – Tehnički detalji

__init__.py transformiše običan direktorijum u Python paket. Ovo omogućava import sistema – možeš koristiti from paket.modul import funkcija. Fajl se izvršava kada se paket prvi put importuje, što omogućava inicijalizaciju paketa. Moderna Python praksa dozvoljava i namespace pakete (bez init.py), ali eksplicitni paketi su i dalje standard za većinu projekata.

🎈 ZABAVNA ČINJENICA: Ime fajlova sa dve donje crte (__init__, __main__, __pycache__) Python-isti duhovito zovu “dunder” fajlovima (double-underscore). Zato ćeš često čuti „dodaj dunder init u folder”.

Kreiranje profesionalne strukture

Vreme je da stvorimo strukturu koja će pratiti našeg Učitelja Vasu kroz celo putovanje. Svaki folder ima svoju jasnu namenu i razlog postojanja.

📚 NIVO 1 – Korak po korak kreiranje

Otvori postojeći projekat u PyCharm-u:
- File → Open
- Pronađi i selektuj “ucitelj-vasa” folder koji smo povezali sa GitHub-om u Dan -1
- Klikni OK
Kreiraj glavne foldere:
- Desni klik na “ucitelj-vasa” → New → Directory
- Kreiraj redom: src, tests, docs
Kreiraj podfoldere u src:
- Desni klik na src → New → Directory
- Kreiraj: ai_services, web_api, utils

PyCharm sa kreiranom strukturom foldera

🚀 NIVO 2 – Objašnjenje strukture

ucitelj-vasa/
├── src/              # Glavni izvorni kod
│   ├── ai_services/  # AI integracije (OpenAI, Claude, itd)
│   ├── web_api/      # FastAPI endpoints (od nedelje 2)
│   └── utils/        # Pomoćne funkcije
├── tests/            # Automatski testovi
├── docs/             # Projektna dokumentacija

📊 DIJAGRAM: Vizuelni tok razvoja

[Koder] → [PyCharm IDE] → [Struktura Projekta]
   │             │                 │
   ↓             ↓                 ↓
Piše kod   Organizuje fajlove    ┌─── src/ (Python kod)
                                 ├─── tests/ (Testovi)
                                 ├─── docs/ (Dokumentacija)
                                 └─── config fajlovi (.env, .gitignore)

Ova struktura omogućava separation of concerns – svaki deo koda ima svoje mesto. To olakšava navigaciju, održavanje i timski rad.

Transformisanje foldera u Python pakete

Sada ćemo obične foldere pretvoriti u Python pakete dodavanjem magičnih __init__.py fajlova.

📚 NIVO 1 – Dodavanje init.py

Za svaki od sledećih foldera:

src/
src/ai_services/
src/web_api/
src/utils/

Uradi sledeće:

Desni klik na folder → New → Python File
Kao ime ukucaj: __init__ (bez .py, PyCharm će dodati)
Ostavi fajl prazan i sačuvaj (Ctrl+S)

PyCharm New Python File dijalog

🚀 NIVO 2 – Zašto baš ovi folderi?

Ne dodajemo __init__.py u tests/ i docs/ jer oni neće biti Python paketi. Tests folder će sadržati test fajlove koje pytest automatski pronalazi, a docs je za dokumentaciju (Markdown fajlovi). Samo folderi sa Python kodom koji želimo da importujemo trebaju biti paketi.

💡 PRO TIP: Dok si još mali projekat, __init__.py može da bude prazan, ali već sada probaj da u njega staviš minimalnu inicijalizaciju, npr. __all__ = [] ili verziju paketa. Kasnije, kada dodaš nove module, samo upišeš ime modula u __all__ i dobijaš „centralnu tablu sadržaja” za ceo paket.

Praktična implementacija

Konfiguracioni fajlovi projekta

Svaki profesionalan Python projekat ima standardne konfiguracione fajlove. Kreirajmo ih:

📊 DIJAGRAM: Interakcija konfiguracionih fajlova

         [GitHub]
            ↑
(`git push` ignoriše fajlove)
            │
      .gitignore ───────────────[Tvoj Lokalni Projekat]────────────── .env
                                           │                             │
                                           ↓                             ↓
                                    requirements.txt  ───(instalira)───> python-dotenv
                                           │                             │
                                           ↓                             ↓
                                      [Virtuelno Okruženje] <──(čita tajne)── [Tvoj Kod (`src`)]

1. .gitignore – šta ne želimo na GitHub-u:

Desni klik na root → New → File → .gitignore:

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
venv/
env/
ENV/

# IDE
.idea/
.vscode/
*.swp
*.swo

# Environment variables
.env
.env.local
*.env

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

# Distribution / packaging
dist/
build/
*.egg-info/

2. requirements.txt – lista biblioteka:

Kreiraj requirements.txt sa:

python-dotenv==1.0.1

Zatim u terminalu:

pip install -r requirements.txt

3. .env – mesto za tajne podatke:

Kreiraj .env fajl:

# API ključevi će biti ovde
# NIKAD ne commit-uj ovaj fajl!
OPENAI_API_KEY=your-key-here

⚠️ VAŽNO: .env je već u .gitignore – tako čuvamo API ključeve!

🔄 VEŽBA: Pre nego što kreneš dalje, otvori terminal i pokreni:

python -m pip freeze > requirements-dev.txt

Ovime praviš snapshot svih trenutno instaliranih paketa u novo-kreiranom requirements-dev.txt. Zatim probaj da obrišeš virtuelno okruženje, kreiraš ga ponovo i instaliraš iz oba fajla kako bi uvežbao vraćanje identične radne sredine na drugom računaru.

Ažuriranje README.md – profesionalna prezentacija

Ažuriraj postojeći README.md (koji smo kreirali u Dan -1) da reflektuje novu strukturu:

# Učitelj Vasa - AI Asistent za Učenje Programiranja

## 📚 O Projektu

Učitelj Vasa je AI-powered asistent kreiran kroz 28-dnevni praktični kurs AISYNTHESIS akademije. 
Cilj je pomoći početnicima da savladaju osnove programiranja kroz interakciju sa AI asistentom.

## 🚀 Trenutni Status

- ✅ Dan -3: Python 3.13+ instaliran
- ✅ Dan -2: PyCharm unified edition podešen
- ✅ Dan -1: GitHub repository kreiran
- ✅ Dan 0: Profesionalna struktura projekta
- ⏳ Dan 1: Prvi Python modul (sutra)

## 🛠️ Tehnologije

- **Python** 3.13+
- **PyCharm** unified edition
- **python-dotenv** za environment varijable
- Uskoro: OpenAI API, FastAPI, SQLite

## 📁 Struktura Projekta

    ucitelj-vasa/
    ├── src/                    # Izvorni kod
    │   ├── __init__.py
    │   ├── ai_services/       # AI integracije
    │   ├── web_api/          # Web API (od nedelje 2)
    │   └── utils/            # Pomoćne funkcije
    ├── tests/                 # Testovi
    ├── docs/                  # Dokumentacija
    ├── .env                   # Environment varijable (ne commit-uj!)
    ├── .gitignore            # Git ignore pravila
    ├── requirements.txt      # Python dependencies
    └── README.md            # Ovaj fajl

## 🔧 Instalacija

1. Kloniraj repository:

    git clone https://github.com/[tvoj-username]/ucitelj-vasa.git
    cd ucitelj-vasa

2. Kreiraj virtuelno okruženje (preporučeno):

    python -m venv venv
    source venv/bin/activate  # Na Windows: venv\Scripts\activate

3. Instaliraj dependencies:

    pip install -r requirements.txt

## 👤 Autor

[Tvoje ime] - Student AISYNTHESIS akademije

## 📄 Licenca

MIT License - slobodno koristi za učenje!

Napomena: Ne zaboravi da zameniš [tvoj-username] sa svojim GitHub korisničkim imenom i [Tvoje ime] sa svojim imenom!

💡 PRO TIP: Dobra praksa je da README.md bude prva dokumentacija koju ažuriraš nakon svake promene. Ova struktura projekta je skoro identična šablonu koji se koristi za deploy-ovanje Python aplikacija na Google Cloud Run ili Google Cloud Functions. Kada dođe vreme da Učitelj Vasa postane dostupan svima na internetu, bićeš u savršenoj poziciji!

Dokumentacija projekta

U docs/ folderu kreiraj development_log.md:

# Razvojni Dnevnik - Učitelj Vasa

## Dan 0: Struktura Projekta ([datum])

### Šta je urađeno:
- ✅ Kreirana profesionalna folder struktura
- ✅ Dodati __init__.py fajlovi za Python pakete  
- ✅ Kreiran .gitignore sa standardnim pravilima
- ✅ Postavljen requirements.txt sa python-dotenv
- ✅ Kreiran .env za čuvanje API ključeva
- ✅ README.md ažuriran sa novom strukturom

### Naučene lekcije:
- Python paketi zahtevaju __init__.py fajlove
- .env fajlovi čuvaju tajne podatke van koda
- Dobra struktura je temelj svakog projekta

### Za sutra (Dan 1):
- Kreirati vasa_core.py sa prvim funkcijama
- Naučiti rad sa Python modulima i importima

🎯 ALTERNATIVNO REŠENJE: Umesto ručnog kreiranja svega, možeš napisati automatski set-up skript:

# setup_scaffold.py
import pathlib

FOLDERS = [
    "src/ai_services",
    "src/web_api",
    "src/utils",
    "tests",
    "docs"
]

FILES = {
    ".gitignore": "venv/\n__pycache__/\n.env\n",
    "requirements.txt": "python-dotenv==1.0.1\n",
    ".env": "# API keys go here\n"
}

root = pathlib.Path(__file__).parent
for f in FOLDERS:
    (root / f).mkdir(parents=True, exist_ok=True)
    (root / f / "__init__.py").touch()

for name, content in FILES.items():
    (root / name).write_text(content)

print("Projekat spreman! 🚀")

Pokreni python setup_scaffold.py i skript ti munjevito postavlja strukturu. Savršeno za hackathone gde je svaka sekunda dragocena!

Česte greške i rešenja

❌ GREŠKA: ModuleNotFoundError: No module named 'dotenv'
💡 REŠENJE: Nisi instalirao biblioteke. U terminalu pokreni: pip install -r requirements.txt

❌ GREŠKA: PyCharm ne prepoznaje src kao Python paket
💡 REŠENJE: Proveri da li postoji src/__init__.py fajl. Zatim: desni klik na src → Mark Directory as → Sources Root

🔬 DETALJNIJE: Zašto je “Mark Directory as -> Sources Root” važno? Kada pokrećeš Python skripte, Python pretražuje listu foldera definisanu u PYTHONPATH promenljivoj da bi pronašao module koje želiš da uvezeš. PyCharm interno upravlja ovom listom za tvoj projekat. Kada označiš src kao “Sources Root”, ti praktično kažeš PyCharm-u: “Dodaj ovaj src folder u PYTHONPATH za ovaj projekat”.

❌ GREŠKA: .gitignore ne radi – .env se još uvek vidi u Git-u
💡 REŠENJE: Ako si već commit-ovao .env, prvo ga ukloni: git rm --cached .env pa ponovo commit-uj

❌ GREŠKA: Permission denied kada kreiram .env ili .gitignore
💡 REŠENJE: Na Windows-u, neki antivirusi blokiraju fajlove sa tačkom. Privremeno onemogući antivirus ili kreiraj kroz PyCharm

❌ GREŠKA: Terminal pokazuje 'python' is not recognized
💡 REŠENJE: Koristi PyCharm terminal (ne CMD). Ako i dalje ne radi, probaj python3 umesto python

⚡ SAVET ZA OPTIMIZACIJU: Kada tvoj projekat poraste na 100+ fajlova, folder struktura postaje kritična za brzinu razvoja. Dobro organizovan kod znači da PyCharm ili drugi IDE alati brže indeksiraju fajlove (što može ubrzati učitavanje projekta i do 5 puta), import naredbe su kraće i logičnije, a pronalaženje grešaka je lakše jer instinktivno znaš gde da tražiš.

Proveri svoje razumevanje

[NIVO 1]:

Zašto svaki Python paket mora imati init.py fajl?
Šta je svrha .gitignore fajla?
Gde čuvamo tajne podatke kao što su API ključevi?

[NIVO 2]:

Koja je razlika između obične folder strukture i Python paketa?
Zašto koristimo odvojene foldere za ai_services, web_api i utils?
Kako bi proširio strukturu da podrži i frontend deo aplikacije?

🤔 MINI-KVIZ:

Zašto je pip install -e . zgodan tokom razvoja i kako ga deinstaliraš kada završiš?
Koja dva fajla služe kao „filter” za poverljive ili privremene podatke u projektu, i koja je razlika u njihovoj primeni (.gitignore vs .env)?
Zamislimo da si zaboravio da dodaš __init__.py u src/web_api/. Koju grešku očekuješ pri importu i kako je najbrže rešiti?

Git commit za danas

git add .
git commit -m "Dan 0: Postavljena profesionalna struktura projekta sa Python paketima"
git push

Čestitam! Postavio si temelje za projekat koji će rasti narednih 28 dana! Učitelj Vasa sada ima svoj dom sa sobama za različite funkcionalnosti. 🏗️

🎈 ZABAVNA ČINJENICA: Microsoft je u Visual Studio Code timu analizirao 20 000 javnih GitHub repoa i otkrio da je upravo struktura „src/tests/docs” najčešći šablon za Python projekte starije od godinu dana — dokaz da si na pravom putu!

Sutra Učitelj Vasa uči

Sutra pravimo prvi korak ka oživljavanju Vase! Kreiraćemo vasa_core.py fajl i napisati prve Python funkcije. Učitelj Vasa će dobiti svoje prve prave sposobnosti – moći će da pozdravi korisnike i prikaže osnovne informacije o sebi. Biće to mali, ali značajan korak ka pravom AI asistentu!

📚 REČNIK DANAŠNJE LEKCIJE:

Python paket (Package): Folder koji sadrži init.py fajl i može sadržati Python module
init.py: Specijalni fajl koji označava da je folder Python paket
.gitignore: Fajl koji definiše šta Git treba da ignoriše
.env: Fajl za čuvanje osetljivih podataka (API ključevi) van koda
requirements.txt: Lista svih eksternih biblioteka potrebnih za projekat
Virtuelno okruženje (venv): Izolovano Python okruženje za projekat
PYTHONPATH: Sistemska promenljiva koja govori Python-u gde da traži module
Separation of Concerns (SoC): Princip razdvajanja različitih funkcionalnosti u zasebne celine

Dan 0/28: Struktura projekta Učitelj Vasa