Fauke

På jamska (jämtska): "fauke" — en kort tid, en liten stund.

A self-hosted time reporting web app for consultants who fill out the same hours in multiple systems. Report once, export everywhere.

---

Quick Start

# Clone and start
git clone <repo-url> && cd fauke
docker compose up --build

• Frontend: http://localhost:5174
• API: http://localhost:3001
• Database: PostgreSQL on port 5433

Features

• Calendar View — Monthly grid, click any day to log hours with color-coded project chips
• Table View — Spreadsheet-style: rows = days, columns = projects, inline totals
• Projects — Create & color-code projects, manage via the Projects panel
• Export — Download CSV or PDF reports for any month
• Integration Webhooks — Trigger real-time sync via secure webhook endpoint
• Docker Compose — One command to spin up the full stack

Integration Webhooks

• Endpoint: POST /api/integrations/webhooks/:integrationId/sync
• Auth header: x-fauke-webhook-secret: <FAUKE_WEBHOOK_SECRET>
• Body (optional): userId, externalEmployeeId, from, to, event
• If no user filter is provided, all assigned users (with external ID) are synced.

Tech Stack

Layer	Tech
Frontend	React 18 + TypeScript + Vite
Styling	Tailwind CSS 3
Backend	Express + TypeScript
Database	PostgreSQL 16
ORM	Prisma
PDF	PDFKit
Deploy	Docker Compose

Project Structure

fauke/
├── docker-compose.yml
├── backend/
│   ├── Dockerfile
│   ├── prisma/              # Schema & migrations
│   └── src/
│       ├── index.ts         # Express app entry
│       ├── auth.ts          # JWT auth helpers
│       ├── db.ts            # Prisma client
│       ├── routes/
│           ├── auth.ts      # Login/me endpoints
│           ├── admin.ts     # Admin users endpoints
│           ├── projects.ts  # CRUD /api/projects
│           ├── entries.ts   # CRUD /api/entries
│           ├── export.ts    # CSV & PDF /api/export
│           ├── integrations.ts # Admin integrations endpoints
│           └── plugins.ts   # Plugin browser/test/execute API
│       └── plugins/         # Plugin interface, registry, built-ins
├── frontend/
│   ├── Dockerfile
│   ├── index.html
│   └── src/
│       ├── App.tsx          # Main app shell
│       ├── api.ts           # API client
│       ├── types.ts         # TypeScript types
│       ├── dateUtils.ts     # Date helpers
│       └── components/
│           ├── Header.tsx
│           ├── LoginPage.tsx
│           ├── AdminPanel.tsx
│           ├── IntegrationsPanel.tsx
│           ├── PluginBrowser.tsx
│           ├── CalendarView.tsx
│           ├── TableView.tsx
│           ├── EntryModal.tsx
│           ├── ProjectManager.tsx
│           └── Toast.tsx
├── overview.md              # Architecture & roadmap
└── todo.md                  # Development tracking

Development

# Start all services with hot reload
docker compose up --build

# Run Prisma migrations manually
docker compose exec backend npx prisma migrate dev

# Stop everything
docker compose down

Roadmap

• v1.0 — MVP + basic auth (completed)
• v1.5 — Admin integrations layer (completed, mock adapters)
• v2.0 — Plugin system + plugin browser UI (current)
• v3.0 — Multi-user with auth & team support

See overview.md for full architecture details and todo.md for task tracking.