# nimble-123/cap-fiori-timetracking architecture

> Architecture diagram of the GitHub repository nimble-123/cap-fiori-timetracking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nimble-123/cap-fiori-timetracking
- Repository: https://github.com/nimble-123/cap-fiori-timetracking

## Overview

#### 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: [`db/data-model.cds`](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/db/data-model.cds) (Domain & Persistence Model), [`srv/track-service/track-service.cds`](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/track-service.cds) (TrackService), [`mta.yaml`](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/mta.yaml) (BTP Bound Services), [`srv/track-service/handler/handlers/TimeEntryHandlers.ts`](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/handler/handlers/TimeEntryHandlers.ts) (Operation Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["CAP Model"]
  node_root_model["CAP Model Entry<br/>CDS entrypoints<br/>[index.cds]"]
  node_domain_model[("Domain &amp; Persistence Model<br/>CDS persistence<br/>[data-model.cds]")]
  node_attachments_model["Attachment Model<br/>CDS extension<br/>[attachments.cds]"]
  node_seed_data[("Master &amp; Seed Data<br/>CAP data")]
  node_cap_persistence[("CAP Persistence<br/>SQLite / HANA HDI")]
end

subgraph group_service["Service Runtime"]
  node_track_api{{"TrackService<br/>OData service<br/>[track-service.cds]"}}
  node_ui_annotations["Fiori Metadata &amp; Policy<br/>CDS annotations<br/>[annotations.cds]"]
  node_admin_api{{"AdminService<br/>OData service<br/>[admin-service.cds]"}}
  node_service_bootstrap["Service Bootstrap<br/>CAP runtime<br/>[track-service.ts]"]
  node_handler_composition["Handler Setup &amp; Registry<br/>composition layer<br/>[HandlerSetup.ts]"]
  node_service_container["Service Container<br/>DI container"]
  node_operation_handlers["Operation Handlers<br/>CAP handlers"]
  node_commands["Business Commands<br/>command layer"]
  node_domain_services["Calculation &amp; Balance Services<br/>domain services"]
  node_generation_strategies["Generation Strategies<br/>strategy layer"]
  node_repositories["Repositories<br/>data access"]
end

subgraph group_ui["UI Applications"]
  node_timetable_ui["Timetable<br/>Fiori Elements UI5<br/>[manifest.json]"]
  node_activity_ui["Activity Type Maintenance<br/>Fiori Elements UI5<br/>[manifest.json]"]
  node_dashboard_ui["Time Tracking Dashboard<br/>MVC UI5<br/>[Component.ts]"]
end

subgraph group_platform["BTP Services"]
  node_holiday_api{{"German Holiday API<br/>external API"}}
  node_btp_bindings{{"BTP Bound Services<br/>Cloud Foundry services<br/>[mta.yaml]"}}
  node_ams_policy["AMS Authorization Policy<br/>DCL policy<br/>[schema.dcl]"]
end

node_root_model -->|"loads"| node_domain_model
node_domain_model -->|"extended by"| node_attachments_model
node_seed_data -->|"seeds"| node_domain_model
node_domain_model -->|"persisted through"| node_cap_persistence
node_track_api -->|"projects"| node_domain_model
node_ui_annotations -->|"annotates"| node_track_api
node_service_bootstrap -->|"implements"| node_track_api
node_service_bootstrap -->|"initializes"| node_handler_composition
node_handler_composition -->|"routes events to"| node_operation_handlers
node_service_container -->|"provides dependencies"| node_operation_handlers
node_operation_handlers -->|"invokes"| node_commands
node_commands -->|"applies policy"| node_domain_services
node_commands -->|"selects"| node_generation_strategies
node_commands -->|"persists via"| node_repositories
node_repositories -->|"accesses"| node_cap_persistence
node_domain_services -->|"looks up holidays"| node_holiday_api
node_timetable_ui -->|"consumes OData"| node_track_api
node_activity_ui -->|"consumes OData"| node_admin_api
node_dashboard_ui -->|"consumes OData"| node_track_api
node_btp_bindings -.->|"provides HANA"| node_cap_persistence
node_btp_bindings -.->|"provides connectivity"| node_holiday_api
node_ams_policy -->|"configures authorization"| node_btp_bindings

click node_root_model "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/index.cds"
click node_domain_model "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/db/data-model.cds"
click node_attachments_model "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/db/attachments.cds"
click node_track_api "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/track-service.cds"
click node_ui_annotations "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/annotations.cds"
click node_admin_api "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/admin-service/admin-service.cds"
click node_service_bootstrap "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/track-service.ts"
click node_handler_composition "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/handler/setup/HandlerSetup.ts"
click node_service_container "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/handler/container/ServiceContainer.ts"
click node_operation_handlers "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/handler/handlers/TimeEntryHandlers.ts"
click node_timetable_ui "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/app/timetable/webapp/manifest.json"
click node_activity_ui "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/app/manage-activity-types/webapp/manifest.json"
click node_dashboard_ui "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/app/timetracking/webapp/Component.ts"
click node_btp_bindings "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/mta.yaml"
click node_ams_policy "https://github.com/nimble-123/cap-fiori-timetracking/blob/main/ams/dcl/schema.dcl"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_model,node_domain_model,node_attachments_model,node_seed_data,node_cap_persistence toneBlue
class node_track_api,node_ui_annotations,node_admin_api,node_service_bootstrap,node_handler_composition,node_service_container,node_operation_handlers,node_commands,node_domain_services,node_generation_strategies,node_repositories toneAmber
class node_timetable_ui,node_activity_ui,node_dashboard_ui toneMint
class node_holiday_api,node_btp_bindings,node_ams_policy toneRose
```

## Components

### CAP Model

- [CAP Model Entry](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/index.cds): CDS entrypoints · Loads database and service models. · `index.cds`
- [Domain & Persistence Model](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/db/data-model.cds): CDS persistence · Users, projects, entries, statuses, code lists, and customizing. · `db/data-model.cds`
- [Attachment Model](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/db/attachments.cds): CDS extension · `db/attachments.cds`
- **Master & Seed Data**: CAP data
- **CAP Persistence**: SQLite / HANA HDI · SQLite locally and HANA HDI on BTP.

### Service Runtime

- [TrackService](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/track-service.cds): OData service · Operational time-tracking API and actions. · `srv/track-service/track-service.cds`
- [Fiori Metadata & Policy](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/annotations.cds): CDS annotations · Defines UI behavior, authorization, field controls, and value helps. · `srv/track-service/annotations.cds`
- [AdminService](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/admin-service/admin-service.cds): OData service · Administrative reference-data exposure. · `srv/admin-service/admin-service.cds`
- [Service Bootstrap](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/track-service.ts): CAP runtime · Initializes TrackService handler wiring. · `srv/track-service/track-service.ts`
- [Handler Setup & Registry](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/handler/setup/HandlerSetup.ts): composition layer · Maps CAP lifecycle and action events to handlers. · `srv/track-service/handler/setup/HandlerSetup.ts`
- [Service Container](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/handler/container/ServiceContainer.ts): DI container · Constructs handlers, commands, services, repositories, and factories. · `srv/track-service/handler/container/ServiceContainer.ts`
- [Operation Handlers](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/srv/track-service/handler/handlers/TimeEntryHandlers.ts): CAP handlers · Time entry, generation, and balance transport handlers. · `srv/track-service/handler/handlers/TimeEntryHandlers.ts`
- **Business Commands**: command layer · Validates and executes time-entry and generation operations.
- **Calculation & Balance Services**: domain services · Time calculation, balances, and holiday policy.
- **Generation Strategies**: strategy layer · Selects monthly or yearly generation algorithms.
- **Repositories**: data access · Isolates time entry, customizing, and user access.

### UI Applications

- [Timetable](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/app/timetable/webapp/manifest.json): Fiori Elements UI5 · `app/timetable/webapp/manifest.json`
- [Activity Type Maintenance](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/app/manage-activity-types/webapp/manifest.json): Fiori Elements UI5 · `app/manage-activity-types/webapp/manifest.json`
- [Time Tracking Dashboard](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/app/timetracking/webapp/Component.ts): MVC UI5 · `app/timetracking/webapp/Component.ts`

### BTP Services

- **German Holiday API**: external API · Holiday lookup via Connectivity and Destination.
- [BTP Bound Services](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/mta.yaml): Cloud Foundry services · HANA, auth, AMS, storage, malware scanning, logging, Connectivity, and Destination. · `mta.yaml`
- [AMS Authorization Policy](https://github.com/nimble-123/cap-fiori-timetracking/blob/main/ams/dcl/schema.dcl): DCL policy · `ams/dcl/schema.dcl`

## Connections

- 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