# sushmac639-prog/claimsiq architecture

> Architecture diagram of the GitHub repository sushmac639-prog/claimsiq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sushmac639-prog/claimsiq
- Repository: https://github.com/sushmac639-prog/claimsiq

## Overview

ClaimIQ is an insurance policy and claims management API. Users authenticate, receive JWTs, and use role-gated endpoints to administer users and policies, create claims against active policies, add notes, and advance claims through a validated status workflow. The route handlers own database operations and audit/history writes; shared dependencies enforce authentication and roles. The excerpts show the main route, security, schema, and persistence relationships. The health endpoint is documented but only its database-session dependency is indexed; other README capabilities are represented where documented.

Main entry points: [`app/db/session.py`](https://github.com/sushmac639-prog/claimsiq/blob/main/app/db/session.py) (DB sessions), [`app/main.py`](https://github.com/sushmac639-prog/claimsiq/blob/main/app/main.py) (FastAPI app), [`app/api/routes/auth.py`](https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/auth.py) (Authentication), [`app/api/deps.py`](https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/deps.py) (Auth dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entry"]
  node_app["FastAPI app<br/>[main.py]"]
  node_health["Health checks<br/>[health.py]"]
end

subgraph group_access["Identity and access"]
  node_auth["Authentication<br/>[auth.py]"]
  node_identity["Auth dependencies<br/>[deps.py]"]
  node_security["JWT and passwords<br/>[security.py]"]
  node_users["User administration<br/>[users.py]"]
  node_user_schema["User schemas<br/>[user.py]"]
  node_auth_schema["Auth schemas<br/>[auth.py]"]
end

subgraph group_operations["Insurance operations"]
  node_policies["Policy management<br/>[policies.py]"]
  node_policy_schema["Policy schemas<br/>[policy.py]"]
  node_claims["Claim workflow<br/>[claims.py]"]
  node_claim_schema["Claim and note schemas<br/>[claim.py]"]
end

subgraph group_persistence["Persistence"]
  node_settings["Configuration<br/>[config.py]"]
  node_session["DB sessions<br/>[session.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_postgres[("PostgreSQL")]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"routes to"| node_health
node_app -->|"routes to"| node_auth
node_app -->|"routes to"| node_users
node_app -->|"routes to"| node_policies
node_app -->|"routes to"| node_claims
node_auth -->|"requires current user"| node_identity
node_auth -->|"verifies and issues tokens"| node_security
node_auth -->|"queries users"| node_session
node_auth -->|"validates token input"| node_auth_schema
node_auth -->|"returns profile"| node_user_schema
node_identity -->|"decodes access token"| node_security
node_identity -->|"loads user"| node_session
node_users -->|"requires admin role"| node_identity
node_users -->|"hashes password"| node_security
node_users -->|"reads and writes users"| node_session
node_users -->|"validates user data"| node_user_schema
node_policies -->|"checks access"| node_identity
node_policies -->|"reads and writes policies"| node_session
node_policies -->|"validates policy data"| node_policy_schema
node_claims -->|"checks access"| node_identity
node_claims -->|"reads and writes claims"| node_session
node_claims -->|"validates claim data"| node_claim_schema
node_claims -->|"records audit and history"| node_models
node_health -->|"checks database"| node_session
node_session -->|"loads database URL"| node_settings
node_session -->|"opens sessions"| node_postgres
node_session -.->|"persists domain records"| node_models

click node_app "https://github.com/sushmac639-prog/claimsiq/blob/main/app/main.py"
click node_health "https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/health.py"
click node_auth "https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/auth.py"
click node_identity "https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/deps.py"
click node_security "https://github.com/sushmac639-prog/claimsiq/blob/main/app/core/security.py"
click node_users "https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/users.py"
click node_user_schema "https://github.com/sushmac639-prog/claimsiq/blob/main/app/schemas/user.py"
click node_auth_schema "https://github.com/sushmac639-prog/claimsiq/blob/main/app/schemas/auth.py"
click node_policies "https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/policies.py"
click node_policy_schema "https://github.com/sushmac639-prog/claimsiq/blob/main/app/schemas/policy.py"
click node_claims "https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/claims.py"
click node_claim_schema "https://github.com/sushmac639-prog/claimsiq/blob/main/app/schemas/claim.py"
click node_settings "https://github.com/sushmac639-prog/claimsiq/blob/main/app/core/config.py"
click node_session "https://github.com/sushmac639-prog/claimsiq/blob/main/app/db/session.py"
click node_models "https://github.com/sushmac639-prog/claimsiq/blob/main/app/db/models.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_app,node_health,node_client toneBlue
class node_auth,node_identity,node_security,node_users,node_user_schema,node_auth_schema toneAmber
class node_policies,node_policy_schema,node_claims,node_claim_schema toneMint
class node_settings,node_session,node_models,node_postgres toneRose
```

## Components

### API entry

- [FastAPI app](https://github.com/sushmac639-prog/claimsiq/blob/main/app/main.py): `app/main.py`
- [Health checks](https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/health.py): `app/api/routes/health.py`

### Identity and access

- [Authentication](https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/auth.py): `app/api/routes/auth.py`
- [Auth dependencies](https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/deps.py): `app/api/deps.py`
- [JWT and passwords](https://github.com/sushmac639-prog/claimsiq/blob/main/app/core/security.py): `app/core/security.py`
- [User administration](https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/users.py): `app/api/routes/users.py`
- [User schemas](https://github.com/sushmac639-prog/claimsiq/blob/main/app/schemas/user.py): `app/schemas/user.py`
- [Auth schemas](https://github.com/sushmac639-prog/claimsiq/blob/main/app/schemas/auth.py): `app/schemas/auth.py`

### Insurance operations

- [Policy management](https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/policies.py): `app/api/routes/policies.py`
- [Policy schemas](https://github.com/sushmac639-prog/claimsiq/blob/main/app/schemas/policy.py): `app/schemas/policy.py`
- [Claim workflow](https://github.com/sushmac639-prog/claimsiq/blob/main/app/api/routes/claims.py): `app/api/routes/claims.py`
- [Claim and note schemas](https://github.com/sushmac639-prog/claimsiq/blob/main/app/schemas/claim.py): `app/schemas/claim.py`

### Persistence

- [Configuration](https://github.com/sushmac639-prog/claimsiq/blob/main/app/core/config.py): `app/core/config.py`
- [DB sessions](https://github.com/sushmac639-prog/claimsiq/blob/main/app/db/session.py): `app/db/session.py`
- [Domain models](https://github.com/sushmac639-prog/claimsiq/blob/main/app/db/models.py): `app/db/models.py`
- **PostgreSQL**

### Other components

- **API client**

## Connections

- API client → FastAPI app: sends requests (evidence: `app/main.py`)
- FastAPI app → Health checks: routes to (evidence: `app/main.py`)
- FastAPI app → Authentication: routes to (evidence: `app/main.py`)
- FastAPI app → User administration: routes to (evidence: `app/main.py`)
- FastAPI app → Policy management: routes to (evidence: `app/main.py`)
- FastAPI app → Claim workflow: routes to (evidence: `app/main.py`)
- Authentication → Auth dependencies: requires current user (evidence: `app/api/routes/auth.py`)
- Authentication → JWT and passwords: verifies and issues tokens (evidence: `app/api/routes/auth.py`)
- Authentication → DB sessions: queries users (evidence: `app/api/routes/auth.py`)
- Authentication → Auth schemas: validates token input (evidence: `app/api/routes/auth.py`)
- Authentication → User schemas: returns profile (evidence: `app/api/routes/auth.py`)
- Auth dependencies → JWT and passwords: decodes access token (evidence: `app/api/deps.py`)
- Auth dependencies → DB sessions: loads user (evidence: `app/api/deps.py`)
- User administration → Auth dependencies: requires admin role (evidence: `app/api/routes/users.py`)
- User administration → JWT and passwords: hashes password (evidence: `app/api/routes/users.py`)
- User administration → DB sessions: reads and writes users (evidence: `app/api/routes/users.py`)
- User administration → User schemas: validates user data (evidence: `app/api/routes/users.py`)
- Policy management → Auth dependencies: checks access (evidence: `app/api/routes/policies.py`)
- Policy management → DB sessions: reads and writes policies (evidence: `app/api/routes/policies.py`)
- Policy management → Policy schemas: validates policy data (evidence: `app/api/routes/policies.py`)
- Claim workflow → Auth dependencies: checks access (evidence: `app/api/routes/claims.py`)
- Claim workflow → DB sessions: reads and writes claims (evidence: `app/api/routes/claims.py`)
- Claim workflow → Claim and note schemas: validates claim data (evidence: `app/api/routes/claims.py`)
- Claim workflow → Domain models: records audit and history (evidence: `app/api/routes/claims.py`)
- Health checks → DB sessions: checks database (evidence: `app/api/routes/health.py`)
- DB sessions → Configuration: loads database URL (evidence: `app/db/session.py`)
- DB sessions → PostgreSQL: opens sessions (evidence: `app/db/session.py`)
- DB sessions → Domain models: persists domain records
