> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture and resource model

> Understand system boundaries, resource ownership, relationships, and the responsibilities of each integration component.

The JobHandy Public API is a synchronous REST interface. Customer systems initiate every public request; the current public v1 contract does not define webhook endpoints or event subscriptions.

## System boundary

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    subgraph Customer[Customer environment]
        HRIS[HRIS / HCM]
        PAY[Payroll system]
        INT[Integration service]
        SEC[Secret manager]
        LOG[Logs and monitoring]
        HRIS --> INT
        PAY --> INT
        SEC --> INT
        INT --> LOG
    end

    subgraph JobHandy[JobHandy]
        API[Public API v1]
        PORTAL[Administration portal]
        DATA[Authorized tenant data]
        FILES[Authorized documents]
        PORTAL --> DATA
        API --> DATA
        API --> FILES
    end

    INT -->|HTTPS + X-API-Key| API
    ADMIN[Authorized administrator] --> PORTAL
```

## Responsibility split

| Responsibility                             | Customer integration |                           JobHandy API |
| ------------------------------------------ | -------------------: | -------------------------------------: |
| Store the API key securely                 |                  Yes |                                     No |
| Schedule polling and synchronization       |                  Yes |                                     No |
| Map source fields to API fields            |                  Yes |                                     No |
| Generate and log `X-Request-ID`            |          Recommended |                    Echoes or generates |
| Enforce API-key scope                      |                   No |                                    Yes |
| Validate request schema and business state |                   No |                                    Yes |
| Reconcile ambiguous write outcomes         |                  Yes |        Provides current resource state |
| Protect downloaded files after retrieval   |                  Yes | Protects API access and download scope |

## Resource ownership

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    KEY[API key scope] --> TEN[Tenant]
    TEN --> DIV[Division hierarchy]
    TEN --> EMP[Employees]
    TEN --> EXP[Payroll export documents]
    EMP --> ORD[Orders]
    EMP --> INC[Incidents]
    ORD --> OA[Order attachments]
    INC --> IA[Incident attachments]
```

| Resource                | Owning boundary                       | Public write capabilities                                     |
| ----------------------- | ------------------------------------- | ------------------------------------------------------------- |
| Tenant                  | API-key scope                         | No tenant create, update, or delete operation                 |
| Division                | One tenant                            | Create and update                                             |
| Employee                | Zero or one tenant; optional division | Create and update supported fields                            |
| Order                   | One tenant and one employee           | Read and record one HR decision from the documented state     |
| Incident                | Employee in authorized scope          | Create, update supported fields, upload permitted attachments |
| Payroll export document | One tenant                            | Read metadata and download available file                     |

## Write side effects

| Operation                   | Persistent effect                        | Additional side effect                  | Dry-run behavior                 |
| --------------------------- | ---------------------------------------- | --------------------------------------- | -------------------------------- |
| Create employee             | Creates account                          | Sends password setup email              | No account and no email          |
| Update employee             | Changes supported fields                 | None stated by the contract             | No persistence                   |
| Decide order                | Stores final HR decision                 | Sends corresponding notifications       | No decision and no notifications |
| Create incident             | Creates incident                         | Assigns reporter and lifecycle metadata | No persistence                   |
| Update incident             | Changes supported incident fields        | Server lifecycle rules can apply        | No persistence                   |
| Upload incident attachments | Stores permitted files                   | None stated by the contract             | Validates without storage        |
| Create division             | Creates hierarchy node                   | None stated by the contract             | No persistence                   |
| Update division             | Changes hierarchy/name/order/cost center | None stated by the contract             | No persistence                   |

The OpenAPI contract is authoritative. Do not assume additional emails, notifications, or downstream actions that are not documented.

## Identifier relationships

Resource IDs are opaque application identifiers. Do not derive business meaning from their characters or order.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Tenant ID
  -> used for X-Tenant-ID and tenant fields
Division ID
  -> used for parentId and employee divisionId
Employee ID
  -> used by orders and incidents
Order attachment ID
  -> used only with the order attachment download endpoint
Payroll export document ID
  -> used for metadata retrieval and download
```

## Integration model

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Source as Customer source system
    participant Integration as Integration service
    participant API as JobHandy Public API
    participant Target as Customer target system

    Source->>Integration: Change, schedule, or user decision
    Integration->>API: HTTPS request + credential + request ID
    API->>API: Authenticate, scope, validate, apply documented rules
    API-->>Integration: Resource or error + X-Request-ID
    Integration->>Integration: Persist checkpoint and reconcile result
    Integration->>Target: Apply downstream change or file import
```

<Note>
  The public contract defines request and response behavior. Customer-specific business ownership, schedules, field mappings, and downstream retention remain part of the integration design.
</Note>