- HTML 65.8%
- Go 16%
- TypeScript 15%
- SCSS 2.4%
- JavaScript 0.5%
- Other 0.3%
| .claude | ||
| backend | ||
| container | ||
| frontend | ||
| graphify-out | ||
| helm | ||
| .gitlab-ci.yml | ||
| CLAUDE.md | ||
| Dockerfile.backend | ||
| Dockerfile.frontend | ||
| README.md | ||
| renovate.json | ||
Timetracker
Timetracker is a time tracking application for a German fire brigade. It consists of:
- a Go backend with Gin, Gorm, OIDC authentication, statistics, and PDF export
- a React frontend with responsive desktop/mobile layouts and light/dark mode
Features
- OIDC login with automatic user creation on first login
- personal time tracking with function selection and start/stop workflow
- manual editing of personal entries and personal statistics
- admin dashboard with member statistics, function statistics, and PDF export
- admin management for trackable functions
- installable PWA with offline app-shell caching
Project structure
Requirements
- Go
1.26.1 - Node.js
22+ - Yarn
1.x
Local setup
1. Install frontend dependencies
cd frontend
yarn install
2. Configure environment
The backend loads environment variables automatically via .env.
Example:
DB_DRIVER=sqlite
DB_NAME=./database.db
EXECUTE_MIGRATIONS=true
OIDC_ISSUER_URL=https://your-oidc.example.org/realms/firebrigade
OIDC_CLIENT_ID=timetracker
OIDC_CLIENT_SECRET=change-me
OIDC_ADMIN_EMAILS=admin@example.org
OIDC_ADMIN_GROUP=timetracker-admins
COOKIE_SECURE=false
GIN_MODE=debug
Notes:
- For local SQLite development, the default database file is
backend/database.db. - For PostgreSQL, set
DB_DRIVER=postgresand provideDB_HOST,DB_PORT(default5432),DB_USER,DB_PASSWORD,DB_NAME, plus optionalDB_SSLMODEandDB_TIMEZONE. - For Microsoft SQL Server, set
DB_DRIVER=mssqland provideDB_HOST,DB_PORT(default1433),DB_USER,DB_PASSWORD,DB_NAME, plus optionalDB_ENCRYPTandDB_TRUST_SERVER_CERTIFICATE. - If no admin exists yet, the first logged-in user can be promoted automatically.
- Manual admin assignment through the application is disabled. After bootstrap, admin access is controlled only through
OIDC_ADMIN_GROUPandOIDC_ADMIN_EMAILS. OIDC_ADMIN_GROUPmust match the group value in the OIDC claims exactly. If your provider emits group paths such as/timetracker-admins, configure that full value.- During login, the backend resolves groups from both the ID token and the OIDC
userinfoendpoint when available, and logs the resulting group list for the user. - Admin assignment is synchronized on login. If a user no longer matches
OIDC_ADMIN_GROUPorOIDC_ADMIN_EMAILS, they are downgraded touseron their next successful OIDC login. - If you run behind TLS and a reverse proxy, set
COOKIE_SECURE=true. OIDC_REDIRECT_URLis optional. If it is not set, the backend derives the callback URL automatically from the incoming request host and scheme and uses/api/v1/auth/callback.- If you are behind a reverse proxy, make sure it forwards the original scheme correctly, for example with
X-Forwarded-Proto.
3. Run the backend
cd backend
go run .
The backend starts on http://localhost:8080 by default.
4. Run the frontend dev server
cd frontend
yarn dev
The frontend runs on http://localhost:5173.
Dev proxy
The Vite dev server proxies all /api/* requests to the backend so the frontend can call the API without CORS setup during development.
Default proxy target:
http://localhost:8080
You can override it with:
VITE_API_PROXY_TARGET=http://localhost:8080 yarn dev
Production build
Frontend
cd frontend
yarn build
This writes the SPA bundle to frontend/dist.
The frontend is packaged as a Progressive Web App with:
manifest.webmanifestfor install metadata- SVG app icons and favicon
- a service worker that caches the app shell and static assets for offline startup
Backend
cd backend
go build ./...
The backend serves the built frontend automatically when frontend/dist is present.
Docker build
The backend Dockerfile builds both the frontend and the backend binary:
docker build -f Dockerfile.backend -t timetracker .
API documentation
Swagger UI is exposed at:
http://localhost:8080/api/docs/index.html
If you update Swagger annotations, regenerate the docs from backend:
swag init
Default seeded functions
On a fresh database, the backend seeds a few default functions:
- Atemschutz
- Maschinist
- Gruppenführung
- Sicherheitswache
Common development commands
cd backend && env GOCACHE=/tmp/ffk-go-cache go build ./...
cd frontend && yarn build