Kako je složen LumenSpark

LumenSpark je interni alat za vođenje projekata u agenciji (LumenHope PM). Zamjenjuje Jira/ClickUp i objedinjuje: projekte, zadatke (Kanban ploča), evidenciju radnog vremena, odsustva, troškove, izvještaje i analitiku - te povlači podatke iz Clockifyja i Jire.

Koriste ga četiri tipa korisnika: superadmin, admin, voditelj projekta (PM) i zaposlenik. Svaki vidi i smije različite stvari (vidi poglavlje o ulogama).

Najnoviji sloj je AI pomoć (Anthropic Claude): od ⌘K trake za pitanja do izvršnog sažetka. Pravilo je strogo - brojke uvijek računa kod, AI ih samo opisuje ljudskim jezikom (vidi poglavlje o AI-u).

Namjerno je biran jednostavan, klasičan stack bez velikih frameworka - lakše ga je hostati na običnom cPanel serveru i lakše ga je razumjeti.

LumenSpark ima tri jasna sloja: preglednik (ono što korisnik vidi), server (PHP) i baza. Kad korisnik nešto klikne, frontend pošalje zahtjev na jedan ulaz na serveru - api/index.php - koji prepozna što se traži, proslijedi pravom kontroleru, a ovaj razgovara s bazom i vrati odgovor.

• ① Zahtjev - frontend šalje fetch POST s poljem action (npr. get_projects) i sigurnosnim CSRF tokenom.
• ② Upit - router u mapi ruta nađe kontroler; on provjeri prijavu i izvrši pripremljeni SQL upit (PDO).
• ③ Odgovor - baza vrati podatke, kontroler ih pošalje kao JSON, frontend osvježi ekran (render()).

Cijela aplikacija živi u mapi app/. Prvo gdje je što, a zatim klikabilni pregled svih kontrolera, JS modula i CSS datoteka.

• app/
  • index.html - jedina HTML stranica (SPA)
  • config.php - pristup bazi (ne dira se)
  • api/ - backend (PHP): router + 37 kontrolera
  • js/ - frontend: 79 modula
  • css/ - 73 CSS (71 učitanih)
  • language/ - prijevodi hr / en / de
  • install/ - instalacija + migracije baze
  • tests/ - automatski testovi
  • assets/ - slike, logo, fontovi
  • uploads/ - avatari, logotipi (učitano)

Klikabilni pregled koda

Odaberi skupinu, klikni stavku - desno se otvori popis metoda/funkcija, varijabli i kratko objašnjenje.

Router (api/index.php)

Frontend uvijek šalje POST zahtjev s poljem action (npr. "get_projects"). Router ima mapu ruta koja svaku akciju spaja s kontrolerom i metodom (ukupno 180 ruta):

$routes = [
  'get_projects'  => [Projects::class, 'getAll'],
  'save_project'  => [Projects::class, 'save'],
  'move_task'     => [Kanban::class,   'moveTask'],
  // ... još 177 ruta
];

Router također vraća uvijek JSON i ima globalni „hvatač grešaka" - ako nešto pukne, korisnik dobije uredan JSON, a ne ružnu PHP grešku.

BaseController - zajednička osnova

Svaki kontroler nasljeđuje BaseController, koji nudi alate koje svi koriste:

• respond($data) - vrati uspješan JSON odgovor
• respondError(code, msg, status) - vrati grešku
• validate($rules) - provjeri ulazna polja (required|min|max|email|numeric|date)
• requireAuth() - zahtijeva prijavu (inače 401)
• requireAdmin() - zahtijeva admin/superadmin ulogu (inače 403)

public function getAll(): void {
    $this->requireAuth();                       // 1. mora biti prijavljen
    $rows = $this->pdo
        ->query("SELECT * FROM ls_projects ORDER BY name ASC")
        ->fetchAll();                            // 2. dohvati iz baze
    $this->respond($rows);                       // 3. vrati JSON
}

Sigurnost

Sve tablice imaju prefiks ls_. Glavne:

Kako se mijenja shema

Ne dira se baza „ručno napamet". Promjene idu kroz datoteke install/migrate_*.php ili kroz SQL koji se zalijepi u phpMyAdmin (server nema pristup information_schema, pa se koriste samo SHOW + izmjene po tablici).

Frontend je SPA (Single Page Application) - postoji samo index.html, a JavaScript mijenja sadržaj bez ponovnog učitavanja stranice. index.html učitava ~89 skripti određenim redom (redoslijed je bitan).

Memorija - state.js (objekt S)

Sve što aplikacija „pamti" dok radi živi u jednom globalnom objektu S: koji je ekran otvoren (S.activeTab), tko je prijavljen (S.currentUser, S.currentUserRole), učitani projekti i članovi (S.projectsDB, S.membersDB) itd.

Pokretanje - boot.js

Prikazuje preloader, vodi prijavu (doLogin), postavlja korisnika (setCurrentUser) i slaže izbornik prema ulozi (_applyRoleSidebar - skriva/pokazuje stavke).

Crtanje ekrana - render.js

Funkcija renderTab() gleda S.activeTab i poziva pravu funkciju za taj ekran:

function renderTab(){
  if (S.activeTab === 'dashboard') { renderDashboard(); return; }
  if (S.activeTab === 'kanban')    { renderKanban();    return; }
  if (S.activeTab === 'projects_db'){ renderProjectsDB(); return; }
  // … itd.
}

Klikovi - events.js

Umjesto da svaki gumb ima svoj onclick, koristi se delegacija: jedan slušač na cijelom dokumentu hvata klik i gleda atribut data-action.

document.addEventListener('click', function(e){
  var t = e.target.closest('[data-action]');
  if (!t) return;
  var act = t.getAttribute('data-action');   // npr. "edit-proj"
  // … pozovi odgovarajuću funkciju
});

Prijevodi - language/

Tekstovi se ne pišu „tvrdo" nego kroz funkciju t('kljuc'), koja vrati prijevod za trenutni jezik (hr/en/de). Ako prijevod ne postoji, vrati se sam ključ.

Da sve izgleda jednako, postoji jedan izvor istine za stil u app.css: tokeni (boje, razmaci, zaobljenja) i kanonske komponente koje se koriste posvuda.

Tokeni (varijable boja)

Boje se nikad ne pišu kao „goli" hex, nego preko varijabli - promjena na jednom mjestu mijenja cijelu aplikaciju.

--brand:#1c4532;  --green:#0a7c4e;  --blue:#0066cc;
--bg:#f4f4f0;     --bg2:#ffffff;    --border:#ddddd8;

Kanonske komponente

Modul table-enhance automatski daje svim tablicama sortiranje (klik na zaglavlje) i nježni zeleni rollover reda pod mišem.

Kako je CSS posložen (slojevi)

CSS se gradi u slojevima - od temelja prema gore. Svaki viši sloj smije koristiti i nadograditi ono ispod sebe, ali temelj (app.css) ne ovisi ni o čemu.

Redoslijed učitavanja - „koji se vuku"

index.html učitava 71 CSS datoteke točnim redom. Najvažnije pravilo: app.css ide PRVI, jer definira tokene i komponente o kojima ovise svi ostali.

Vidljivost u izborniku i dozvole na serveru ovise o ulozi:

Matrica prava (RBAC) - can()

Prava se ne provjeravaju usporedbom imena uloge razbacanom po kodu, nego kroz jednu matricu: tablice ls_roles (uloge) × ls_role_modules (koji modul i na kojoj razini smije uloga). Postoji jedan središnji „rješavač":

• Backend: Permissions.php napuni prava u sesiju jednom pri loginu; svaka akcija pita can(modul, razina).
• Frontend: perms.js nudi lsCan() / canModule() - sučelje sakrije ono što korisnik ne smije.

Na frontendu izbornik slaže _applyRoleSidebar() (liste empHidden/empVisible u boot.js). Sigurnosno pravilo ostaje: prava zaštita je na serveru.

Aplikacija povlači podatke iz vanjskih alata. Postavljaju se u Postavke → Konektori (API ključ se šifrira prije spremanja).

• Clockify - sinkronizira projekte, članove i evidenciju vremena.
• Jira - uvozi zadatke (issues) u ls_tasks kao Kanban kartice (REST v3 proxy).
• Slack - šalje obavijesti o događajima (npr. novi zadatak, odobreno odsustvo) na kanal.
• Anthropic Claude - AI pozivi za sažetke i narative (vidi poglavlje o AI-u).

Uvoz je jednosmjeran i ponovljiv (pull/upsert): povuče i ažurira, ali ne piše natrag u Clockify/Jiru. Pokreće se ručno i siguran je za ponavljanje (idempotentan).

LumenSpark ima ugrađen AI sloj koji koristi Anthropic Claude. On ne zamjenjuje aplikaciju - on je pomoćnik koji čita gotove podatke i objašnjava ih ljudskim jezikom.

Šest živih AI značajki

Kako radi (jednostavno)

• api/Ai.php je tanki shim - jedna ulazna točka koja zove Anthropic API i vraća tekst.
• API ključ je šifriran (AES-256-CBC) u ls_settings; postavlja se u Konektorima.
• Svaki poziv se zabilježi u ls_ai_usage (model, tokeni, procijenjeni trošak) - da se vidi potrošnja.
• api/AiAssist.php i api/AiNarrate.php prvo sastave snapshot (gotove brojke iz PHP-a), pa to pošalju AI-ju da napiše tekst.

Kanban je vizualna ploča sa zadacima koji putuju kroz kolone (npr. Za napraviti → U tijeku → Gotovo). Cilj mu je zamijeniti Jiru za svakodnevni rad.

Polje board_type na projektu određuje radi li se o čistom Kanbanu ili Scrumu (sa sprintovima). Zadaci se mogu uvesti iz Jire (jednosmjerno, ponovljivo), a na svaki zadatak može se klokati vrijeme (timer veže sat uz karticu).

Sigurnost je posložena u više slojeva. Junioru je najvažnije zapamtiti: provjera je uvijek na serveru, a podaci se nikad ne lijepe „goli" u SQL.

Exec360 je jedan ekran za upravu - „cockpit" koji na jednom mjestu pokaže novac i smjer tvrtke: KPI kartice (prihod, trošak, dobit, marža), grafove i kratak AI sažetak.

• exec_snapshot - jedan endpoint koji agregira sve ključne brojke (PHP ih izračuna).
• exec_narrative - AI iz tog snapshota napiše Sažetak → Financije → Rizici → Preporuke.
• Izvještaj se može izvesti u PDF (pdfmake, dizajn iz reporting-pdf.css).

Uz aplikaciju postoji i mala Chrome ekstenzija (MV3, verzija 1.1.3) za brzo klokanje vremena. Zaposlenik iz alatne trake preglednika odabere projekt i zadatak te pokrene/zaustavi mjerenje - bez otvaranja cijele aplikacije.

Pratimo što se dogodi kad korisnik klikne npr. „Spremi projekt":

1. Klik u pregledniku - gumb ima data-action="save-project".
2. events.js uhvati klik i pozove pravu JS funkciju.
3. Funkcija pozove apiCall('save_project', podaci) - to je fetch POST na /api/ s X-CSRF-Token u zaglavlju.
4. api/index.php pročita action i u mapi ruta nađe [Projects, 'save'].
5. Kontroler napravi requireAuth(), provjeri podatke i izvrši pripremljeni SQL upit.
6. Vrati JSON: { "ok": true, … } ili grešku { "ok": false, "error": … }.
7. JS osvježi S (memoriju) i ponovno nacrta ekran (renderTab()).

Postoje tri sloja provjere - cilj je da se promjena ne „provuče" i pokvari nešto drugo:

Objava ide ručno preko cPanel File Managera (nema terminala ni lokalnog servera):

1. Uploadaj promijenjene datoteke u odgovarajuće mape (js/, css/, api/…).
2. Promijeni ?v= broj uz CSS/JS u index.html - inače preglednik servira staru verziju iz keša.
3. Promjene baze: zalijepi SQL u phpMyAdmin.
4. Otvori aplikaciju uz Ctrl + Shift + R (tvrdi refresh).

Kratki podsjetnik - koraci kad dodaješ npr. novi popis na ekranu:

1. Backend: dodaj metodu u kontroler + upiši rutu u mapu $routes (s requireAuth() i pripremljenim upitom).
2. Frontend: napravi ime.js + ime.css (isti prefiks) i registriraj ih u index.html.
3. Komponente: koristi kanonske (.th/.tr, .s-btn, .badge…) i tokene - bez golog hexa.
4. Jezici: dodaj tekstove u sva tri (hr/en/de).
5. Uloge: provjeri tko smije vidjeti/raditi (gate na serveru!).
6. Testovi: dodaj guard u tests/ i provjeri lint.
7. Deploy: bumpaj ?v= i Ctrl+Shift+R.