Firmowid

Firmowid to aplikacja dla małych firm w Polsce: faktury w KSeF (wystawianie i pobieranie), automatyczne parowanie przelewów z bankiem (Open Banking), ewidencja czasu pracy w projektach, urlopy, delegacje i płace.

Kod jest na licencji AGPL-3.0. Możesz uruchomić Firmowid na własnym serwerze albo korzystać z wersji hostowanej na firmowid.pl (plan Darmowy 0 zł, bez limitu faktur).

Note for English speakers: Firmowid is a web app for small Polish businesses: KSeF e-invoicing, automatic bank-to-invoice matching, time tracking, leave and payroll. Open source under AGPL-3.0. The product targets the Polish market, so this README is in Polish; the commands in Szybki start work as-is, and env.template documents the local configuration in English.

Co potrafi

Zrzuty pochodzą z lokalnej instalacji na danych testowych z seedów.

Chcesz pomóc?

Zapraszamy! Poprawki błędów, usprawnienia UX, dokumentacja i nowe pomysły są mile widziane. Do pracy nad kodem nie potrzebujesz dostępu do infrastruktury Alergeek Ventures: aplikacja działa lokalnie na danych testowych, a wszystkie zewnętrzne integracje są opcjonalne.

• Masz pytanie albo pomysł? Załóż dyskusję.
• Widzisz błąd? Otwórz issue z krokami do odtworzenia.
• Chcesz coś zmienić? Zrób fork, branch i pull request do main. Przy większej zmianie najpierw opisz pomysł w issue lub dyskusji, żeby nie pracować na próżno.
• Podatności bezpieczeństwa zgłaszaj prywatnie, zgodnie z SECURITY.md.

Zanim wyślesz PR, przejrzyj Jak pracujemy: uruchom mix check i nazwij commity według Conventional Commits.

Dwie rzeczy wymagają maintainera:

• PR z forka nie dostaje sekretów CI, więc pełne CI (tłumaczenia, build, jakość, Docker) nie uruchomi się na nim. Maintainer przeniesie twój commit na branch w repozytorium i tam uruchomi CI.
• Nowe i zmienione teksty widoczne w UI (Gettext) muszą mieć tłumaczenia w Accent, zanim CI przejdzie. Dostęp do Accent mają maintainerzy, więc napisz w PR, które teksty się zmieniły. Szczegóły: CI: snapshoty tłumaczeń.

Z czego jest zbudowany

• Elixir, Phoenix LiveView i Ash Framework
• PostgreSQL (ParadeDB), S3 (SeaweedFS) i Gotenberg do PDF-ów, uruchamiane lokalnie w kontenerach (local/compose.yml)

Katalog	Zawartość
lib/firmowid	Domena i logika biznesowa (zasoby Ash: faktury, KSeF, finanse, płace…)
lib/firmowid_web	Interfejs webowy (LiveView), ułożony według funkcji
lib/firmowid_mcp	Serwer MCP dla asystentów AI
lib/firmowid_ui	Komponenty UI wspólne dla przeglądarki i MCP
priv/repo/seeds*	Dane testowe do lokalnego developmentu

Testy leżą obok kodu, który testują (*_test.exs w lib/).

Szybki start (bez Infisical)

Ta ścieżka jest dla wszystkich spoza zespołu Alergeek Ventures. Zespół pobiera wspólną konfigurację z Infisical (opis niżej); tutaj generujesz ją lokalnie.

Potrzebujesz: Elixira i Erlanga w wersjach z .tool-versions, Node.js 26, Dockera lub Podmana z compose oraz kilku paczek systemowych. Instrukcja jest w sekcji Instalacja środowiska; na Nixie wystarczy direnv allow.

1. Pobierz kod

git clone https://github.com/Alergeek-Ventures/firmowid.git
cd firmowid

(albo sklonuj swój fork).

2. Skonfiguruj lokalne zmienne

cp env.template .env.worktree
echo "SECRET_KEY_BASE=$(openssl rand -base64 48)" >> .env.worktree
echo "OAUTH2_SIGNING_SECRET=$(openssl rand -base64 48)" >> .env.worktree
echo "CLOAK_VAULT_KEY=$(openssl rand -base64 32)" >> .env.worktree

Klucze są generowane tylko dla twojej lokalnej bazy. .env.worktree jest w .gitignore, więc nie trafi do repozytorium.

Następnie wyłącz Infisical w powłoce, w której uruchamiasz polecenia mix (najwygodniej dopisz to do profilu powłoki):

export AV_SKIP_INFISICAL=1

Bez tej flagi aplikacja próbuje pobrać konfigurację z Infisical i kończy się błędem. Flaga musi być ustawiona w środowisku powłoki; wpis w .env.worktree nie zadziała, bo ten plik jest wczytywany dopiero po kroku Infisical.

3. Uruchom bazę danych, S3 i Gotenberga

docker compose -f local/compose.yml up -d    # albo: podman compose -f local/compose.yml up -d

Usługi nasłuchują na portach 5433 (PostgreSQL), 4566 (S3) i 3000 (Gotenberg). Jeśli któryś jest zajęty, zmień go w .env.worktree (dla bazy ustaw też DATABASE_URL) i przekaż te same DB_PORT, S3_PORT, GOTENBERG_PORT do polecenia compose.

4. Zainstaluj zależności i przygotuj bazę

mix setup

mix setup pobiera zależności Elixira i npm, opublikowany katalog tłumaczeń (bez klucza Accent), tworzy bazę, uruchamia migracje, seeduje dane testowe i buduje assety. Pierwsze uruchomienie kompiluje całą aplikację i trwa kilka minut.

Tłumaczenia są pobierane dla bieżącego commita albo origin/main. W forku trzymaj main zsynchronizowany z upstreamem, żeby taki snapshot istniał.

5. Włącz serwer

mix phx.server

Wejdź na localhost:4000, zaloguj się jako [email protected] / kolejka123456 i otwórz /development: znajdziesz tam pełny przewodnik po danych testowych, kontrahentach, projektach i scenariuszach KSeF. Wysłane maile zobaczysz w /mailbox.

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗