HackYeah 2026

Monorepo projektu na HackYeah.

Folder	Co to jest	Stack
find_inv/	client – frontend	Next.js, React, Tailwind
find_inv_server/	server – backend API	FastAPI (Python 3.12+)

Szybki start — jeden skrypt

# Sklonuj repo
git clone https://github.com/akai-org/hackyeah2026.git
cd hackyeah2026

# Linux / Mac — podaj numer swojego agenta (1-5)
bash setup.sh 2

# Windows PowerShell — podaj numer swojego agenta (1-5)
.\setup.ps1 -Agent 2

Skrypt tworzy venv, instaluje zależności, ustawia .env i tworzy Twój branch. Potem uruchom backend i frontend w dwóch osobnych terminalach (instrukcja wyświetli się po setup).

Przed kodowaniem przeczytaj: CONTEXT.md → AGENTS.md → PROMPTS.md (Twój numer)

---

Szybki start — ręcznie

Server (port 8000)

cd find_inv_server
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
fastapi dev app/main.py

Szczegóły (macOS/Linux, testy, dodawanie endpointów): find_inv_server/README.md.

Client (port 3000)

Wymaga Node.js 20+.

cd find_inv
npm install
npm run dev

Frontend: http://localhost:3000 · API: http://localhost:8000 · Swagger: http://localhost:8000/docs

---

Deploy (Docker Compose) — link do demo

Cała aplikacja (FastAPI + Next.js) startuje jednym poleceniem na dowolnym serwerze z Dockerem. Przy pierwszym starcie backend sam wgrywa dane demo i katalog innowacji ROPS do wolumenu hubmi-data (SQLite, ChromaDB, załączniki) — kolejne restarty niczego nie nadpisują.

# lokalnie: http://localhost:3000 (frontend), http://localhost:8000/docs (API)
docker compose up -d --build

# na serwerze z domeną — adresy publiczne trafiają do builda frontendu i do CORS backendu
PUBLIC_APP_URL=https://hubmi.example.pl \
PUBLIC_API_URL=https://api.hubmi.example.pl \
docker compose up -d --build

Zmienna	Domyślnie	Po co
PUBLIC_APP_URL	http://localhost:3000	adres frontendu — dozwolony origin CORS
PUBLIC_API_URL	http://localhost:8000	adres API widziany z przeglądarki (wbudowywany w build Next.js — po zmianie --build)
APP_PORT / API_PORT	3000 / 8000	porty na hoście

Klucze trzymaj w find_inv_server/.env (nie commituj): OPENROUTER_API_KEY (bez niego działają reguły lokalne, bez czatu z modelem i wyszukiwania semantycznego) i ADMIN_TOKEN (panel zgłoszonych potrzeb — zmień z change-me). TLS: postaw przed kontenerami Caddy albo nginx (Let's Encrypt).

Co musi zrobić człowiek, żeby był publiczny link: wykupić VPS (2 vCPU / 4 GB wystarczy) i domenę, ustawić rekordy DNS na oba adresy, wgrać .env z kluczami i uruchomić polecenie wyżej. Koszty: docs/koszty-utrzymania.md.

---

Setup narzędzi AI

Repo z AI skillami dla całego zespołu. Sklonuj i skopiuj pliki — gotowe.

Filozofia

• Żadnego backendu, baz danych ani autoryzacji
• Tylko hardkodowane dane (mocki)
• Tylko happy path
• Liczy się wyłącznie wygląd demo podczas prezentacji

---

Instalacja (jednorazowo)

git clone https://github.com/akai-org/hackyeah2026.git
cd hackyeah2026

# Skopiuj skille do Claude Code
cp -r .claude/skills/. ~/.claude/skills/

# Skopiuj skille uniwersalne (Cursor, Copilot, itp.)
cp -r .agents/skills/. ~/.agents/skills/

# Impeccable — wymaga osobnej instalacji
npx impeccable install

---

Co masz po instalacji

Skill	Do czego
impeccable	Jakość UI — komendy /polish, /delight, /bolder, /critique
transitions-dev	43+ gotowych CSS transitions (modal, card, icon swap, success check…)
gsap-core	Tweeny, easing, stagger
gsap-timeline	Sekwencje animacji
gsap-scrolltrigger	Animacje przy scrollowaniu — robi wrażenie na demo
gsap-plugins	Flip, Draggable, SplitText
gsap-react	GSAP w React (useGSAP hook)
gsap-performance	Optymalizacja animacji
gsap-frameworks	GSAP w Vue / Svelte
gsap-utils	Helpery (clamp, mapRange, interpolate)

---

Workflow na hackathon

Krok 1 — init projektu

/impeccable init

Ustawia kontekst produktu — AI będzie wiedział co budujesz.

Krok 2 — budowanie UI

Mów AI wprost o animacjach, a skille aktywują się automatycznie:

• "add a transition to the modal" → transitions-dev
• "animate the dashboard numbers" → GSAP
• "scroll animation on hero section" → GSAP ScrollTrigger

Krok 3 — dopracowanie wyglądu

/polish     # poprawia spacing, kolory, spójność
/delight    # dodaje wow factor — animacje, detale
/bolder     # mocniejszy, bardziej wyrazisty design
/critique   # pokazuje co wygląda słabo

---

Prompt do wklejenia na początku sesji

Jesteś programistą na hackathonie. Twoim głównym celem jest dowiezienie świetnie wyglądającego dema w jak najkrótszym czasie.

Nie twórz prawdziwej, skomplikowanej logiki biznesowej, backendu, autoryzacji ani baz danych. Skup się w 100% na frontendzie, interfejsie użytkownika (UI/UX) i zrobieniu świetnego pierwszego wrażenia.

Zasady:
- Używaj wyłącznie hardkodowanych danych (mocków)
- Buduj tylko główną ścieżkę użytkownika (happy path)
- Sięgaj po gotowe biblioteki komponentów (shadcn/ui, MUI, Tailwind) zamiast pisać od zera
- Dodawaj fake loading states (spinnery, skeleton loadery) — wyglądają jak prawdziwe dane
- Animacje i przejścia między ekranami robią wrażenie — używaj ich
- Kod ma być jak najprostszy i szybki do napisania

Liczy się wyłącznie to, żeby aplikacja wyglądała na w pełni gotową i sprawną podczas kilkuminutowej prezentacji.