# netresearch/timetracker architecture

> Architecture diagram of the GitHub repository netresearch/timetracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/netresearch/timetracker
- Repository: https://github.com/netresearch/timetracker

## Overview

##### Main components
- Frontend Client:
- User Interface built with HTML/CSS/JS.
- A significant “assets” folder that holds ExtJS libraries, custom JavaScript (e.g., controllers, netresearch widgets, and helper scripts for Jira) and style sheets.
- Web Server and Routing Layer:
- The “public” directory contains the front controller (index.php) and static files.
- Server configuration files (like .htaccess for Apache and nginx-conf.d-default.conf) indicate deployment on common web servers.
- Symfony Application (Backend):
- The “src” directory contains Symfony’s Kernel, Controllers, Entities, Repositories, Services, and Helpers.
- Controllers: Handle incoming HTTP requests (see Controller subdirectory for AdminController, CrudController, etc.).
- Entities and Repositories: Define the domain model (time entries, projects, users, contracts, etc.) and data persistence logic (using Doctrine ORM).
- Services: Business logic for export, subticket synchronization, LDAP integration, and Jira OAuth integration.
- Config and routes: Directories “config” and files like “config/routes.yaml”, “config/services.yaml”, and various environment-specific settings denote application configuration and environment management.
- Database:
- Although not a specific directory, SQL files in the “sql” folder indicate that a MySQL (or MySQL-compatible) database is used to persist time tracking, user, and project data.
- External Integrations:
- LDAP: Helpers and configuration in the “src/Helper” and “src/Security” directories point to LDAP authentication.
- Jira: Detailed instructions in the README and services/controllers for Jira integration (OAuth configuration, consumer key/secret management, ticket work log synchronization).
- External ticketing system integration: Components handling “external ticket system” functionality, where data is translated between external clients and internal tracking.
- Development & Deployment Tools:
- Docker files, docker-compose YAMLs, and other configuration files (.env, composer.json) suggest the application’s multi-environment support.
- CI/CD (GitHub workflows) and testing directories (“tests”, “phpunit.xml.dist”) indicate robust automated testing patterns.

##### Relationships and interactions
- The Web Browser (client) interacts with the Frontend user interface by sending HTTP requests to the Web Server.
- The front controller (public/index.php) forwards these requests to Symfony Controllers, which apply the MVC pattern to process user operations.
- Controllers leverage Services for business logic, which in turn work with Entities/Repositories to retrieve or persist data in the MySQL database.
- For authentication, the system reaches out to LDAP via dedicated helpers (e.g., LdapAuthenticator, LdapClient) and uses environment settings from .env local.
- Integration with Jira and external ticket systems happens via OAuth and API calls as configured in the Jira integration section of the README.
- Assets (JavaScript and CSS) are served from the “public” directory; they interact with the back end via API endpoints (documented in public/api.yml).
- Testing, Docker orchestration, and deployment configurations form part of the overall system health and build automation.

##### Architectural patterns and design principles
- MVC pattern in Symfony: Controllers, Models (Entities/Repositories), and Views (Templates and front-end pages) are clearly separated.
- Layered architecture: A front-end layer (assets, public), a business logic layer (Services, Helpers in src), and a data access layer (Repositories and Entities, working with Doctrine/MySQL).
- Integration and adapter patterns for external systems (Jira OAuth integration, LDAP authentication, external ticket system mapping) allow for loosely coupled services.
- Environment-specific configurations for development, testing, and production (using .env files, config/packages/* directories) underline adherence to best practices in configuration management.

- Rectangles for application components (controllers, services).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    WB("Web Browser/Client"):::frontend
    AS("Assets"):::frontend
    PI("Public/index.php"):::frontend
    SC("Server Config"):::frontend

    %% Symfony Application Layer
    SK("Symfony Kernel"):::backend
    SCtrl("Symfony Controller"):::backend
    SL("Service Layer"):::backend
    ER("Entities & Repositories"):::backend
    CONF("Configuration"):::backend

    %% Data Storage
    DB("MySQL Database"):::database

    %% External Integrations
    LDAPC("LDAP Client"):::external
    LDAPA("LDAP Authenticator"):::external
    JIRA("Jira Integration"):::external
    TICK("Ticket System Integration"):::external

    %% DevOps & Deployment Tools
    DEV("DevOps Tools"):::external

    %% Relationships in Frontend
    WB -->|"loadsAssets"| AS
    WB -->|"httpRequest"| PI
    SC -->|"configures"| PI

    %% Transition to Backend
    PI -->|"initializes"| SK
    SK -->|"routesTo"| SCtrl
    SCtrl -->|"loads_config"| CONF
    SCtrl -->|"invokes"| SL

    %% Backend Processing
    SL -->|"calls"| ER
    ER -->|"persists_to"| DB

    %% External Integrations from Service Layer
    SL -->|"auth_via"| LDAPC
    SL -->|"verifies_via"| LDAPA
    SL -->|"syncs_with"| JIRA
    SL -->|"integrates_with"| TICK

    %% DevOps Support
    DEV -->|"supports"| SK

    %% Click Events
    click AS "https://github.com/netresearch/timetracker/blob/main/assets/app.js"
    click PI "https://github.com/netresearch/timetracker/blob/main/public/index.php"
    click SC "https://github.com/netresearch/timetracker/blob/main/nginx-conf.d-default.conf"
    click SK "https://github.com/netresearch/timetracker/blob/main/src/Kernel.php"
    click SCtrl "https://github.com/netresearch/timetracker/tree/main/src/Controller"
    click SL "https://github.com/netresearch/timetracker/tree/main/src/Services"
    click ER "https://github.com/netresearch/timetracker/tree/main/src/Entity"
    click CONF "https://github.com/netresearch/timetracker/blob/main/config/routes.yaml"
    click DB "https://github.com/netresearch/timetracker/blob/main/sql/000_base.sql"
    click LDAPC "https://github.com/netresearch/timetracker/blob/main/src/Helper/LdapClient.php"
    click LDAPA "https://github.com/netresearch/timetracker/blob/main/src/Security/LdapAuthenticator.php"
    click JIRA "https://github.com/netresearch/timetracker/blob/main/src/Helper/JiraOAuthApi.php"
    click TICK "https://github.com/netresearch/timetracker/blob/main/src/Helper/TicketHelper.php"
    click DEV "https://github.com/netresearch/timetracker/blob/main/.github/workflows/docker-publish.yml"

    %% Style Definitions
    classDef frontend fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef database fill:#fff9c4,stroke:#f57f17,stroke-width:2px;
    classDef external fill:#ffe0b2,stroke:#e65100,stroke-width:2px;
```
