How nimble-123/cap-fiori-timetracking works
Purpose and entry points
CAPture Time is an SAP CAP/TypeScript time-tracking application: time-entry CRUD and status workflow, monthly/yearly generation, time/vacation/sick balances, reference-data administration, and attachments. CAP model loading begins at index.cds, db/index.cds, and srv/index.cds; runtime bootstrap is srv/index.ts. The primary OData API is TrackService at srv/track-service/track-service.cds, implemented by srv/track-service/track-service.ts.
Domain model and persistence
The CDS domain owns users, projects, time entries, statuses, code lists, customizing, and attachment integration. Its persistence boundary is defined in db/data-model.cds, extended by db/attachments.cds and db/ams-attributes.cds; local seed/master data resides under db/data/. CAP abstracts persistence locally (SQLite in development) and targets SAP HANA HDI in BTP.
Service API and presentation contract
TrackService exposes the operational OData surface, actions, and UI metadata; AdminService provides administrative exposure. Key boundaries are srv/track-service/track-service.cds, srv/track-service/annotations.cds, and srv/admin-service/admin-service.cds. CDS annotations define Fiori capabilities, authorization, field controls, value helps, and entity-specific UI behavior rather than embedding those policies in frontend code.
Request orchestration and dependency setup
TrackService initializes handler wiring and maps CAP lifecycle/action events to application handlers. srv/track-service/track-service.ts, srv/track-service/handler/setup/HandlerSetup.ts, and srv/track-service/handler/registry/HandlerRegistrar.ts form this composition boundary. The DI container in srv/track-service/handler/container/ServiceContainer.ts constructs repositories, domain services, validators, strategies, commands, and factories; handlers should consume these abstractions rather than directly instantiate dependencies.
Business-operation pipeline
Handlers separate CAP transport events from business execution: srv/track-service/handler/handlers/TimeEntryHandlers.ts, GenerationHandlers.ts, and BalanceHandlers.ts. They invoke command objects such as commands/time-entry/CreateTimeEntryCommand.ts or commands/generation/GenerateMonthlyCommand.ts. Commands apply validators, use factories for time-entry construction/calculation, then persist through repositories. This supports explicit status transitions (done/release), recalculation, uniqueness/business-rule enforcement, and bulk generation.
Domain services, strategies, and external integration
Domain services concentrate calculations and policy: services/TimeCalculationService.ts, services/TimeBalanceService.ts, and services/HolidayService.ts. Generation commands select monthly/yearly algorithms through strategies/MonthlyGenerationStrategy.ts and YearlyGenerationStrategy.ts. Data access is isolated behind repositories, notably repositories/TimeEntryRepository.ts, CustomizingRepository.ts, and UserRepository.ts. Holiday lookup crosses an external boundary through BTP Connectivity/Destination to the German holiday API; application defaults come from the Customizing singleton.
User applications and deployment
Three UI5 applications consume the OData services: Fiori Elements timetable (app/timetable/webapp/manifest.json), activity-type maintenance (app/manage-activity-types/webapp/manifest.json), and custom MVC dashboard (app/timetracking/webapp/Component.ts). Each has an xs-app.json routing boundary. mta.yaml packages Cloud Foundry modules and bindings for HANA, Application Frontend Service/app router, IAS authentication, AMS authorization policies (ams/dcl/schema.dcl), object storage and malware scanning for attachments, application logging, Connectivity, and Destination services.
Main entry points: data-model.cds Domain & Persistence Model · track-service.cds TrackService · mta.yaml BTP Bound Services · TimeEntryHandlers.ts Operation Handlers
Components 22
CAP Model
- CAP Model Entry · Loads database and service models.
index.cds - Domain & Persistence Model · Users, projects, entries, statuses, code lists, and customizing.
db/data-model.cds - Attachment Model
db/attachments.cds - Master & Seed Data
- CAP Persistence · SQLite locally and HANA HDI on BTP.
Service Runtime
- TrackService · Operational time-tracking API and actions.
srv/track-service/track-service.cds - Fiori Metadata & Policy · Defines UI behavior, authorization, field controls, and value helps.
srv/track-service/annotations.cds - AdminService · Administrative reference-data exposure.
srv/admin-service/admin-service.cds - Service Bootstrap · Initializes TrackService handler wiring.
srv/track-service/track-service.ts - Handler Setup & Registry · Maps CAP lifecycle and action events to handlers.
srv/track-service/handler/setup/HandlerSetup.ts - Service Container · Constructs handlers, commands, services, repositories, and factories.
srv/track-service/handler/container/ServiceContainer.ts - Operation Handlers · Time entry, generation, and balance transport handlers.
srv/track-service/handler/handlers/TimeEntryHandlers.ts - Business Commands · Validates and executes time-entry and generation operations.
- Calculation & Balance Services · Time calculation, balances, and holiday policy.
- Generation Strategies · Selects monthly or yearly generation algorithms.
- Repositories · Isolates time entry, customizing, and user access.
UI Applications
- Timetable
app/timetable/webapp/manifest.json - Activity Type Maintenance
app/manage-activity-types/webapp/manifest.json - Time Tracking Dashboard
app/timetracking/webapp/Component.ts
BTP Services
- German Holiday API · Holiday lookup via Connectivity and Destination.
- BTP Bound Services · HANA, auth, AMS, storage, malware scanning, logging, Connectivity, and Destination.
mta.yaml - AMS Authorization Policy
ams/dcl/schema.dcl
Connections 22
- CAP Model Entry → Domain & Persistence Model: loads
- Domain & Persistence Model → Attachment Model: extended by
- Master & Seed Data → Domain & Persistence Model: seeds
- Domain & Persistence Model → CAP Persistence: persisted through
- TrackService → Domain & Persistence Model: projects
- Fiori Metadata & Policy → TrackService: annotates
- Service Bootstrap → TrackService: implements
- Service Bootstrap → Handler Setup & Registry: initializes
- Handler Setup & Registry → Operation Handlers: routes events to
- Service Container → Operation Handlers: provides dependencies
- Operation Handlers → Business Commands: invokes
- Business Commands → Calculation & Balance Services: applies policy
- Business Commands → Generation Strategies: selects
- Business Commands → Repositories: persists via
- Repositories → CAP Persistence: accesses
- Calculation & Balance Services → German Holiday API: looks up holidays
- Timetable → TrackService: consumes OData
- Activity Type Maintenance → AdminService: consumes OData
- Time Tracking Dashboard → TrackService: consumes OData
- BTP Bound Services → CAP Persistence: provides HANA
- BTP Bound Services → German Holiday API: provides connectivity
- AMS Authorization Policy → BTP Bound Services: configures authorization