# amulyaa-mohan/resolva-timecard-exception-resolution-agent architecture

> Architecture diagram of the GitHub repository amulyaa-mohan/resolva-timecard-exception-resolution-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent
- Repository: https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent

## Overview

Resolva is a deterministic-first, human-in-the-loop timecard exception resolution agent. Its principal workflow brings attendance evidence into the system, detects policy exceptions, drafts a cited correction proposal, validates it deterministically, and presents it for a manager’s approve, edit, or reject decision. Approved corrections remain separate from raw punches, with decisions recorded in an append-only audit trail. The graph includes the frontend review flow, attendance and policy stages, resolution state, and AI/retrieval internals. Some subsystem links are based on the README or source-index references; unsampled implementation details are not asserted as inspected.

Main entry points: [`backend/app/main.py`](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/main.py) (API application), [`backend/app/attendance/ingest.py`](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/ingest.py) (Attendance ingestion and detection), [`backend/app/ai/pipeline.py`](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/ai/pipeline.py) (Proposal pipeline), [`frontend/src/main.tsx`](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/main.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Manager interface"]
  node_web_app["Web application<br/>[main.tsx]"]
  node_resolution_panel["Resolution panel"]
  node_secondary_views["Secondary views<br/>[SecondaryViews.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_ui_contracts["UI contracts<br/>[contracts.ts]"]
end

subgraph group_attendance["Attendance and policy"]
  node_api_server["API application<br/>[main.py]"]
  node_import_routes["Import routes<br/>[imports_router.py]"]
  node_attendance_ingest["Attendance ingestion and detection<br/>[ingest.py]"]
  node_attendance_store[("Attendance evidence store<br/>[postgres.py]")]
  node_attendance_queries["Attendance queries<br/>[queries.py]"]
  node_policy_registry["Policy registry<br/>[registry.py]"]
  node_rules_engine["Deterministic rules<br/>[engine.py]"]
  node_attendance_routes["Attendance routes<br/>[router.py]"]
end

subgraph group_resolution["Resolution and audit"]
  node_resolution_routes["Decision routes<br/>[router.py]"]
  node_resolution_store[("Resolution store<br/>[store.py]")]
  node_audit_events["Audit events<br/>[events.py]"]
end

subgraph group_ai["Proposal and retrieval"]
  node_proposal_pipeline["Proposal pipeline<br/>[pipeline.py]"]
  node_language_assistant["Language assistant<br/>[assistant.py]"]
  node_retrieval["Hybrid retrieval<br/>[hybrid.py]"]
  node_provider_factory["LLM providers<br/>[__init__.py]"]
end

node_manager(("Manager"))
node_external_model{{"LLM service"}}

node_manager -->|"uses"| node_web_app
node_web_app -->|"renders"| node_resolution_panel
node_web_app -->|"renders"| node_secondary_views
node_resolution_panel -->|"requests data"| node_api_client
node_resolution_panel -->|"uses types"| node_ui_contracts
node_secondary_views -->|"uses types"| node_ui_contracts
node_api_client -.->|"calls API"| node_api_server
node_api_server -->|"registers"| node_attendance_routes
node_api_server -->|"registers"| node_resolution_routes
node_api_server -->|"registers"| node_import_routes
node_import_routes -->|"commits imports"| node_attendance_ingest
node_attendance_ingest -->|"writes evidence"| node_attendance_store
node_attendance_ingest -->|"resolves policy"| node_policy_registry
node_attendance_ingest -->|"runs detection"| node_rules_engine
node_attendance_routes -->|"queries attendance"| node_attendance_queries
node_attendance_routes -->|"invokes assistant"| node_language_assistant
node_resolution_routes -->|"loads and decides"| node_resolution_store
node_resolution_store -->|"drafts proposal"| node_proposal_pipeline
node_resolution_store -->|"records decisions"| node_audit_events
node_language_assistant -->|"uses pipeline"| node_proposal_pipeline
node_proposal_pipeline -->|"retrieves evidence"| node_retrieval
node_proposal_pipeline -->|"requests completion"| node_provider_factory
node_provider_factory -.->|"calls model"| node_external_model

click node_web_app "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/main.tsx"
click node_resolution_panel "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/components/ResolutionPanel.tsx"
click node_secondary_views "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/features/SecondaryViews.tsx"
click node_api_client "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/lib/api.ts"
click node_ui_contracts "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/types/contracts.ts"
click node_api_server "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/main.py"
click node_import_routes "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/imports_router.py"
click node_attendance_ingest "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/ingest.py"
click node_attendance_store "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/postgres.py"
click node_attendance_queries "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/queries.py"
click node_policy_registry "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/policies/registry.py"
click node_rules_engine "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/rules/engine.py"
click node_attendance_routes "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/router.py"
click node_resolution_routes "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/resolution/router.py"
click node_resolution_store "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/resolution/store.py"
click node_audit_events "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/audit/events.py"
click node_proposal_pipeline "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/ai/pipeline.py"
click node_language_assistant "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/language/assistant.py"
click node_retrieval "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/retrieval/hybrid.py"
click node_provider_factory "https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/ai/providers/__init__.py"

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_web_app,node_resolution_panel,node_secondary_views,node_api_client,node_ui_contracts toneBlue
class node_api_server,node_import_routes,node_attendance_ingest,node_attendance_store,node_attendance_queries,node_policy_registry,node_rules_engine,node_attendance_routes toneAmber
class node_resolution_routes,node_resolution_store,node_audit_events toneMint
class node_proposal_pipeline,node_language_assistant,node_retrieval,node_provider_factory toneRose
class node_manager,node_external_model toneIndigo
```

## Components

### Manager interface

- [Web application](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Resolution panel](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/components/ResolutionPanel.tsx): `frontend/src/components/ResolutionPanel.tsx`
- [Secondary views](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/features/SecondaryViews.tsx): `frontend/src/features/SecondaryViews.tsx`
- [API client](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [UI contracts](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/frontend/src/types/contracts.ts): `frontend/src/types/contracts.ts`

### Attendance and policy

- [API application](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/main.py): `backend/app/main.py`
- [Import routes](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/imports_router.py): `backend/app/attendance/imports_router.py`
- [Attendance ingestion and detection](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/ingest.py): `backend/app/attendance/ingest.py`
- [Attendance evidence store](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/postgres.py): `backend/app/attendance/postgres.py`
- [Attendance queries](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/queries.py): `backend/app/attendance/queries.py`
- [Policy registry](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/policies/registry.py): `backend/app/policies/registry.py`
- [Deterministic rules](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/rules/engine.py): `backend/app/rules/engine.py`
- [Attendance routes](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/attendance/router.py): `backend/app/attendance/router.py`

### Resolution and audit

- [Decision routes](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/resolution/router.py): `backend/app/resolution/router.py`
- [Resolution store](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/resolution/store.py): `backend/app/resolution/store.py`
- [Audit events](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/audit/events.py): `backend/app/audit/events.py`

### Proposal and retrieval

- [Proposal pipeline](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/ai/pipeline.py): `backend/app/ai/pipeline.py`
- [Language assistant](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/language/assistant.py): `backend/app/language/assistant.py`
- [Hybrid retrieval](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/retrieval/hybrid.py): `backend/app/retrieval/hybrid.py`
- [LLM providers](https://github.com/amulyaa-mohan/resolva-timecard-exception-resolution-agent/blob/main/backend/app/ai/providers/__init__.py): `backend/app/ai/providers/__init__.py`

### Other components

- **Manager**
- **LLM service**

## Connections

- Manager → Web application: uses (evidence: `README.md`)
- Web application → Resolution panel: renders (evidence: `frontend/src/main.tsx`)
- Web application → Secondary views: renders (evidence: `frontend/src/main.tsx`)
- Resolution panel → API client: requests data (evidence: `frontend/src/components/ResolutionPanel.tsx`)
- Resolution panel → UI contracts: uses types (evidence: `frontend/src/components/ResolutionPanel.tsx`)
- Secondary views → UI contracts: uses types (evidence: `frontend/src/features/SecondaryViews.tsx`)
- API client → API application: calls API
- API application → Attendance routes: registers (evidence: `backend/app/main.py`)
- API application → Decision routes: registers (evidence: `backend/app/main.py`)
- API application → Import routes: registers (evidence: `backend/app/main.py`)
- Import routes → Attendance ingestion and detection: commits imports (evidence: `backend/app/attendance/imports_router.py`)
- Attendance ingestion and detection → Attendance evidence store: writes evidence (evidence: `backend/app/attendance/ingest.py`)
- Attendance ingestion and detection → Policy registry: resolves policy (evidence: `backend/app/attendance/ingest.py`)
- Attendance ingestion and detection → Deterministic rules: runs detection (evidence: `backend/app/attendance/ingest.py`)
- Attendance routes → Attendance queries: queries attendance (evidence: `backend/app/attendance/router.py`)
- Attendance routes → Language assistant: invokes assistant (evidence: `backend/app/attendance/router.py`)
- Decision routes → Resolution store: loads and decides (evidence: `backend/app/resolution/router.py`)
- Resolution store → Proposal pipeline: drafts proposal (evidence: `backend/app/resolution/store.py`)
- Resolution store → Audit events: records decisions (evidence: `backend/app/resolution/store.py`)
- Language assistant → Proposal pipeline: uses pipeline (evidence: `backend/app/language/assistant.py`)
- Proposal pipeline → Hybrid retrieval: retrieves evidence (evidence: `backend/app/ai/pipeline.py`)
- Proposal pipeline → LLM providers: requests completion (evidence: `backend/app/ai/pipeline.py`)
- LLM providers → LLM service: calls model
