# charwayyyyyy/opencontract architecture

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

- Interactive diagram: https://gitdiagram.com/charwayyyyyy/opencontract
- Repository: https://github.com/charwayyyyyy/opencontract

## Overview

OpenContract is a public-procurement transparency platform: people explore OCDS lifecycle records, inspect contract timelines and integrity signals, ask grounded questions, and verify documents by hash. Its principal path runs from procurement exploration through API-backed record retrieval to database results; verification hashes files in the browser before checking registered records and anchors. The README documents broader lifecycle coverage and blockchain verification, but Solidity sources are absent from the supplied tree, and several UI and service implementations were not sampled.

Main entry points: [`apps/web/src/services/procurement/queries.ts`](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/services/procurement/queries.ts) (Procurement queries), [`apps/web/src/app/api/v1/analyst/route.ts`](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/analyst/route.ts) (Grounded analyst API), [`packages/database/src/client.ts`](https://github.com/charwayyyyyy/opencontract/blob/main/packages/database/src/client.ts) (Prisma client), [`apps/web/src/components/verification/verify-page.tsx`](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/components/verification/verify-page.tsx) (Document verifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Public experience"]
  node_explore["Procurement explorer"]
  node_contract["Contract detail"]
  node_analyst_ui["Analyst interface"]
  node_verify_ui["Document verifier<br/>[verify-page.tsx]"]
end

subgraph group_procurement["Procurement data"]
  node_search_api["Procurement search API<br/>[route.ts]"]
  node_record_api["Procurement record API<br/>[route.ts]"]
  node_timeline_api["Timeline API<br/>[route.ts]"]
  node_ocds_api["OCDS export API<br/>[route.ts]"]
  node_queries["Procurement queries<br/>[queries.ts]"]
  node_signals["Integrity signals<br/>[statistics.ts]"]
end

subgraph group_verification["Integrity and verification"]
  node_document_check["Hash verification API<br/>[route.ts]"]
  node_blockchain["Blockchain utilities<br/>[blockchain.ts]"]
end

subgraph group_platform["Platform services"]
  node_analyst_api["Grounded analyst API<br/>[route.ts]"]
  node_database_client["Prisma client<br/>[client.ts]"]
  node_database[("Procurement database")]
end

node_citizen(("Citizen / auditor"))
node_gemini{{"Google Gemini"}}
node_base{{"Base Sepolia"}}
node_browser(("User browser"))

node_citizen -->|"browses"| node_explore
node_explore -->|"searches"| node_search_api
node_search_api -->|"invokes"| node_queries
node_record_api -->|"loads"| node_queries
node_timeline_api -->|"loads"| node_queries
node_ocds_api -->|"loads"| node_queries
node_queries -->|"queries"| node_database_client
node_analyst_ui -->|"asks"| node_analyst_api
node_analyst_api -->|"retrieves context"| node_database_client
node_analyst_api -.->|"prompts"| node_gemini
node_analyst_api -->|"uses demo signals"| node_signals
node_citizen -->|"selects document"| node_verify_ui
node_verify_ui -->|"hashes locally"| node_browser
node_verify_ui -->|"submits hash"| node_document_check
node_document_check -->|"looks up hash"| node_database_client
node_document_check -->|"uses anchor data"| node_blockchain
node_blockchain -.->|"checks anchors"| node_base
node_database_client -->|"reads records"| node_database
node_contract -->|"loads record"| node_record_api
node_contract -->|"loads timeline"| node_timeline_api

click node_explore "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/components/procurement/procurement-explorer.tsx"
click node_contract "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/components/procurement/contract-detail.tsx"
click node_analyst_ui "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/components/analyst/analyst-interface.tsx"
click node_verify_ui "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/components/verification/verify-page.tsx"
click node_search_api "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/procurements/route.ts"
click node_record_api "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/procurements/%5Bocid%5D/route.ts"
click node_timeline_api "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/procurements/%5Bocid%5D/timeline/route.ts"
click node_ocds_api "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/ocds/records/%5Bocid%5D/route.ts"
click node_queries "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/services/procurement/queries.ts"
click node_signals "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/services/procurement/statistics.ts"
click node_analyst_api "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/analyst/route.ts"
click node_document_check "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/verify/document/route.ts"
click node_blockchain "https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/lib/blockchain.ts"
click node_database_client "https://github.com/charwayyyyyy/opencontract/blob/main/packages/database/src/client.ts"

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_explore,node_contract,node_analyst_ui,node_verify_ui,node_browser toneBlue
class node_search_api,node_record_api,node_timeline_api,node_ocds_api,node_queries,node_signals toneAmber
class node_document_check,node_blockchain toneMint
class node_analyst_api,node_database_client,node_database toneRose
class node_citizen,node_gemini,node_base toneIndigo
```

## Components

### Public experience

- [Procurement explorer](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/components/procurement/procurement-explorer.tsx): `apps/web/src/components/procurement/procurement-explorer.tsx`
- [Contract detail](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/components/procurement/contract-detail.tsx): `apps/web/src/components/procurement/contract-detail.tsx`
- [Analyst interface](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/components/analyst/analyst-interface.tsx): `apps/web/src/components/analyst/analyst-interface.tsx`
- [Document verifier](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/components/verification/verify-page.tsx): `apps/web/src/components/verification/verify-page.tsx`

### Procurement data

- [Procurement search API](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/procurements/route.ts): `apps/web/src/app/api/v1/procurements/route.ts`
- [Procurement record API](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/procurements/%5Bocid%5D/route.ts): `apps/web/src/app/api/v1/procurements/[ocid]/route.ts`
- [Timeline API](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/procurements/%5Bocid%5D/timeline/route.ts): `apps/web/src/app/api/v1/procurements/[ocid]/timeline/route.ts`
- [OCDS export API](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/ocds/records/%5Bocid%5D/route.ts): `apps/web/src/app/api/v1/ocds/records/[ocid]/route.ts`
- [Procurement queries](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/services/procurement/queries.ts): `apps/web/src/services/procurement/queries.ts`
- [Integrity signals](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/services/procurement/statistics.ts): `apps/web/src/services/procurement/statistics.ts`

### Integrity and verification

- [Hash verification API](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/verify/document/route.ts): `apps/web/src/app/api/v1/verify/document/route.ts`
- [Blockchain utilities](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/lib/blockchain.ts): `apps/web/src/lib/blockchain.ts`

### Platform services

- [Grounded analyst API](https://github.com/charwayyyyyy/opencontract/blob/main/apps/web/src/app/api/v1/analyst/route.ts): `apps/web/src/app/api/v1/analyst/route.ts`
- [Prisma client](https://github.com/charwayyyyyy/opencontract/blob/main/packages/database/src/client.ts): `packages/database/src/client.ts`
- **Procurement database**

### Other components

- **Citizen / auditor**
- **Google Gemini**
- **Base Sepolia**
- **User browser**

## Connections

- Citizen / auditor → Procurement explorer: browses
- Procurement explorer → Procurement search API: searches
- Procurement search API → Procurement queries: invokes
- Procurement record API → Procurement queries: loads
- Timeline API → Procurement queries: loads
- OCDS export API → Procurement queries: loads
- Procurement queries → Prisma client: queries
- Analyst interface → Grounded analyst API: asks
- Grounded analyst API → Prisma client: retrieves context
- Grounded analyst API → Google Gemini: prompts
- Grounded analyst API → Integrity signals: uses demo signals
- Citizen / auditor → Document verifier: selects document
- Document verifier → User browser: hashes locally
- Document verifier → Hash verification API: submits hash
- Hash verification API → Prisma client: looks up hash
- Hash verification API → Blockchain utilities: uses anchor data
- Blockchain utilities → Base Sepolia: checks anchors
- Prisma client → Procurement database: reads records
- Contract detail → Procurement record API: loads record
- Contract detail → Timeline API: loads timeline