afloresc/time-control

Purpose and Deployable Entry Points

Time Control is a labor time-tracking system: a Go HTTP API records work sessions under Spanish labor-control requirements, and a separate React/Vite client provides clock and session views. The API starts at cmd/api/main.go; the browser client boots from time-control-frontend/src/main.jsx into time-control-frontend/src/App.jsx.

API Composition and Routing

The backend is modular by domain and exposes protected user (/me) and administrator (/admin) APIs. Router assembly, middleware placement, and endpoint binding are centralized in internal/router/router.go. Session operations flow handler → service → repository, separating HTTP concerns, business rules, and persistence:

• internal/sessions/handler.go

• internal/sessions/service.go

• internal/sessions/repository.go

Authentication and Authorization Boundary

Firebase is the identity authority. Request middleware validates Bearer JWTs, derives identity/claims, provisions a local user when needed, and places user ID, email, and role in request context. Admin routes add a role gate after authentication. This is the principal external trust boundary:

• internal/auth/firebase.go

• internal/auth/firebase_middleware.go

• internal/admin/handler.go

Work-Session Lifecycle

Authenticated users start and end an active work session or create manual dated intervals; they can retrieve their own session history. The session model represents persisted work-time records, while the service governs lifecycle transitions and repository writes/queries:

• internal/sessions/model.go

• internal/sessions/service.go

• internal/sessions/repository.go

An admin can inspect all sessions and filter them by Firebase/local user ID through the admin-facing routing/handler layer.

Interval and Time Presentation Domain

A distinct intervals module appears to support interval-oriented API behavior alongside the core sessions domain. It has its own HTTP, service, persistence, and model boundaries:

• internal/intervals/handler.go

• internal/intervals/service.go

• internal/intervals/repository.go

On the frontend, clock state and elapsed-time behavior are encapsulated separately from visual active/inactive states:

• time-control-frontend/src/hooks/useClock.js

• time-control-frontend/src/components/clock/ClockActiveSession.jsx

• time-control-frontend/src/components/clock/ClockInactiveSession.jsx

Persistence and Local User Projection

SQLite is the system of record, accessed through GORM, with the checked-in runtime database located at data/timecontrol.db. Firebase identities are projected into a local users table so application roles and session ownership can be queried locally. User persistence is isolated from auth and sessions:

• internal/database/sqlite.go

• internal/users/model.go

• internal/users/repository.go

Frontend Application Boundary

The React client uses Firebase client authentication, maintains auth state in context, protects routes, and calls the backend session API. Its main application flow is auth bootstrap → protected route → clock/sessions page → API request carrying Firebase credentials:

• time-control-frontend/src/Firebase.js

• time-control-frontend/src/context/AuthContext.jsx

• time-control-frontend/src/api/sessionsApi.js

Routing and application shell are separated from feature pages:

• time-control-frontend/src/app/router.jsx

• time-control-frontend/src/components/RequireAuth.jsx

• time-control-frontend/src/pages/Clock.jsx