# null-spectra/cognichain architecture

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

- Interactive diagram: https://gitdiagram.com/null-spectra/cognichain
- Repository: https://github.com/null-spectra/cognichain

## Overview

1. **Overall shape**
   CogniChain is a Next.js 16 / React 19 application that combines a browser UI, server-side API routes, a realtime database layer, an AI analysis layer, and a blockchain anchoring layer. The architecture is centered on evidence and case management for law enforcement.

2. **UI delivery layer**
   The `app/` directory contains the user-facing routes: dashboard (`app/page.tsx`), login, case creation, and case detail views. `app/layout.tsx` likely wires global providers such as theming, while `app/globals.css` and Tailwind CSS v4 define the visual system. The UI is split into reusable components in `components/`, especially `ChatWindow`, `BlockchainFeed`, and theme controls.

3. **Backend API boundary**
   The `pages/api/` directory is the main server boundary. It exposes endpoints for case CRUD, case status updates, evidence upload and download, evidence analysis, image analysis, and AI chat generation. This keeps sensitive operations, file handling, and external-service calls off the client.

4. **Realtime data layer**
   InstantDB is the primary application data store and collaboration layer. The schema in `instant.schema.ts` defines domain entities such as officers, cases, evidence, action logs, and file records. `instant.perms.ts` governs access control, and `lib/db.ts` / `lib/db.admin.ts` separate normal client access from privileged server/admin access.

5. **Case management flow**
   Cases appear to be the core business object. The browser creates or updates a case through the case pages and API routes, while the API persists those changes to InstantDB. Status updates have a dedicated endpoint, suggesting a live workflow around investigation state changes and auditability.

6. **Evidence pipeline**
   Evidence enters through `pages/api/evidence.ts`, then can be analyzed, downloaded, or image-processed via specialized evidence endpoints. The data model implies that each evidence item is linked to a case and a stored file reference, with metadata and derived results preserved in the database.

7. **Blockchain verification layer**
   `lib/blockchain.ts` and the `BlockchainFeed` component indicate that evidence hashes are written to the opBNB network for immutability. The repo uses Ethers.js, so the blockchain layer is a server-side integration that anchors evidence integrity and exposes transaction activity back to the UI as an audit feed.

8. **AI analysis layer**
   `pages/api/chat/generate.ts`, `pages/api/evidence/analyze.ts`, and `pages/api/evidence/analyze-image.ts` show Gemini-powered analysis as a separate service boundary. The UI sends case/evidence context to these endpoints, and the server returns generated insights, discrepancy detection, or image interpretation for investigators.

9. **Identity and access control**
   The project describes role-based security for officers. In architectural terms, that implies authentication at the login route, authorization enforced through InstantDB permissions, and privileged server operations via `db.admin.ts` and secret environment variables.

10. **Auditability and traceability**
   `ActionLog` in the schema, plus blockchain transaction history and status endpoints, form the audit trail. This means the system records both domain changes in InstantDB and tamper-resistant proof on-chain, which is important for evidentiary integrity.

11. **Supporting utilities**
   `lib/hash.ts` and `lib/id.ts` handle low-level integrity and identifier concerns, which are important in evidence systems where stable IDs and hashes matter. These utilities sit below the business logic and are reused across API routes and storage/blockchain operations.

12. **Storage and temporary files**
   The repo includes a `temp/` directory and a storage-focused document, suggesting transient file handling before or during upload. InstantDB Storage appears to be the persistent file layer, while temp is likely used for intermediate processing such as analysis or hashing.

13. **What to draw in an architecture diagram**
   A good diagram should show: browser UI routes on the left; Next.js API routes as the central server layer; InstantDB as the realtime datastore; opBNB as the immutable verification ledger; Gemini as the AI service; and supporting auth/permissions around database and API access. The main data flows are case creation, evidence upload, analysis, and blockchain anchoring, all feeding back into realtime UI updates.

Main entry points: [`instant.schema.ts`](https://github.com/null-spectra/cognichain/blob/main/instant.schema.ts) (Schema), [`app/cases/[caseId]/page.tsx`](https://github.com/null-spectra/cognichain/blob/main/app/cases/[caseId]/page.tsx) (Case Detail), [`pages/api/evidence.ts`](https://github.com/null-spectra/cognichain/blob/main/pages/api/evidence.ts) (Evidence API), [`pages/api/cases.ts`](https://github.com/null-spectra/cognichain/blob/main/pages/api/cases.ts) (Cases API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_app_home["Dashboard<br/>route<br/>[page.tsx]"]
  node_app_login["Login<br/>route<br/>[page.tsx]"]
  node_app_create_case["Create Case<br/>route<br/>[page.tsx]"]
  node_app_case_detail["Case Detail<br/>route<br/>[page.tsx]"]
  node_chat_window["Chat Window<br/>[ChatWindow.tsx]"]
  node_blockchain_feed["Blockchain Feed<br/>[BlockchainFeed.tsx]"]
  node_theme_system["Theme UI<br/>[ThemeProvider.tsx]"]
end

subgraph group_server["Server"]
  node_api_cases["Cases API<br/>route-handler<br/>[cases.ts]"]
  node_api_case_status["Status API<br/>route-handler<br/>[status.ts]"]
  node_api_evidence["Evidence API<br/>route-handler<br/>[evidence.ts]"]
  node_api_evidence_analyze["Analyze API<br/>route-handler<br/>[analyze.ts]"]
  node_api_evidence_image["Image API<br/>route-handler<br/>[analyze-image.ts]"]
  node_api_chat_generate["Chat API<br/>route-handler<br/>[generate.ts]"]
end

subgraph group_data["Data"]
  node_instant_schema[("Schema<br/>[instant.schema.ts]")]
  node_instant_perms["Permissions<br/>access-control<br/>[instant.perms.ts]"]
  node_db_clients[("DB Clients<br/>db-access<br/>[db.ts]")]
end

subgraph group_integrations["Integrations"]
  node_blockchain_lib{{"Blockchain<br/>eth-integration<br/>[blockchain.ts]"}}
end

subgraph group_support["Support"]
  node_hash_utils["Hash Utils<br/>[hash.ts]"]
  node_id_utils["ID Utils<br/>[id.ts]"]
end

node_app_home -->|"load cases"| node_api_cases
node_app_home -->|"show feed"| node_blockchain_feed
node_app_login -.->|"authz"| node_instant_perms
node_app_create_case -->|"create"| node_api_cases
node_app_case_detail -->|"load/update"| node_api_cases
node_app_case_detail -->|"manage evidence"| node_api_evidence
node_app_case_detail -->|"embed chat"| node_chat_window
node_app_case_detail -->|"show proof"| node_blockchain_feed
node_chat_window -->|"send prompt"| node_api_chat_generate
node_api_cases -->|"persist cases"| node_instant_schema
node_api_case_status -->|"update status"| node_instant_schema
node_api_case_status -.->|"enforce access"| node_instant_perms
node_api_evidence -->|"persist evidence"| node_instant_schema
node_api_evidence -->|"hash file"| node_hash_utils
node_api_evidence -->|"assign ids"| node_id_utils
node_api_evidence_analyze -->|"anchor result"| node_blockchain_lib
node_api_evidence_analyze -->|"save findings"| node_instant_schema
node_api_evidence_image -->|"save vision data"| node_instant_schema
node_api_chat_generate -->|"read context"| node_instant_schema
node_instant_schema -.->|"guard data"| node_instant_perms
node_db_clients -->|"connect"| node_instant_schema
node_db_clients -.->|"apply rules"| node_instant_perms
node_blockchain_lib -->|"verify hash"| node_hash_utils
node_blockchain_lib -->|"surface txs"| node_blockchain_feed
node_theme_system -->|"style app"| node_app_home

click node_app_home "https://github.com/null-spectra/cognichain/blob/main/app/page.tsx"
click node_app_login "https://github.com/null-spectra/cognichain/blob/main/app/login/page.tsx"
click node_app_create_case "https://github.com/null-spectra/cognichain/blob/main/app/create-case/page.tsx"
click node_app_case_detail "https://github.com/null-spectra/cognichain/blob/main/app/cases/[caseId]/page.tsx"
click node_chat_window "https://github.com/null-spectra/cognichain/blob/main/components/ChatWindow.tsx"
click node_blockchain_feed "https://github.com/null-spectra/cognichain/blob/main/components/BlockchainFeed.tsx"
click node_theme_system "https://github.com/null-spectra/cognichain/blob/main/components/ThemeProvider.tsx"
click node_api_cases "https://github.com/null-spectra/cognichain/blob/main/pages/api/cases.ts"
click node_api_case_status "https://github.com/null-spectra/cognichain/blob/main/pages/api/cases/[caseId]/status.ts"
click node_api_evidence "https://github.com/null-spectra/cognichain/blob/main/pages/api/evidence.ts"
click node_api_evidence_analyze "https://github.com/null-spectra/cognichain/blob/main/pages/api/evidence/analyze.ts"
click node_api_evidence_image "https://github.com/null-spectra/cognichain/blob/main/pages/api/evidence/analyze-image.ts"
click node_api_chat_generate "https://github.com/null-spectra/cognichain/blob/main/pages/api/chat/generate.ts"
click node_instant_schema "https://github.com/null-spectra/cognichain/blob/main/instant.schema.ts"
click node_instant_perms "https://github.com/null-spectra/cognichain/blob/main/instant.perms.ts"
click node_db_clients "https://github.com/null-spectra/cognichain/blob/main/lib/db.ts"
click node_blockchain_lib "https://github.com/null-spectra/cognichain/blob/main/lib/blockchain.ts"
click node_hash_utils "https://github.com/null-spectra/cognichain/blob/main/lib/hash.ts"
click node_id_utils "https://github.com/null-spectra/cognichain/blob/main/lib/id.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_app_home,node_app_login,node_app_create_case,node_app_case_detail,node_chat_window,node_blockchain_feed,node_theme_system toneBlue
class node_api_cases,node_api_case_status,node_api_evidence,node_api_evidence_analyze,node_api_evidence_image,node_api_chat_generate toneAmber
class node_instant_schema,node_instant_perms,node_db_clients toneMint
class node_blockchain_lib toneRose
class node_hash_utils,node_id_utils toneIndigo
```

## Components

### UI

Browser-facing routes and shared components

- [Dashboard](https://github.com/null-spectra/cognichain/blob/main/app/page.tsx): route · Main investigator dashboard · `app/page.tsx`
- [Login](https://github.com/null-spectra/cognichain/blob/main/app/login/page.tsx): route · Authentication entry screen · `app/login/page.tsx`
- [Create Case](https://github.com/null-spectra/cognichain/blob/main/app/create-case/page.tsx): route · Case creation workflow · `app/create-case/page.tsx`
- [Case Detail](https://github.com/null-spectra/cognichain/blob/main/app/cases/[caseId]/page.tsx): route · Case and evidence view · `app/cases/[caseId]/page.tsx`
- [Chat Window](https://github.com/null-spectra/cognichain/blob/main/components/ChatWindow.tsx): AI chat interface · `components/ChatWindow.tsx`
- [Blockchain Feed](https://github.com/null-spectra/cognichain/blob/main/components/BlockchainFeed.tsx): On-chain activity view · `components/BlockchainFeed.tsx`
- [Theme UI](https://github.com/null-spectra/cognichain/blob/main/components/ThemeProvider.tsx): Theme controls and provider · `components/ThemeProvider.tsx`

### Server

Next.js API routes and backend orchestration

- [Cases API](https://github.com/null-spectra/cognichain/blob/main/pages/api/cases.ts): route-handler · Case CRUD boundary · `pages/api/cases.ts`
- [Status API](https://github.com/null-spectra/cognichain/blob/main/pages/api/cases/[caseId]/status.ts): route-handler · Case status updates · `pages/api/cases/[caseId]/status.ts`
- [Evidence API](https://github.com/null-spectra/cognichain/blob/main/pages/api/evidence.ts): route-handler · Evidence upload and retrieval · `pages/api/evidence.ts`
- [Analyze API](https://github.com/null-spectra/cognichain/blob/main/pages/api/evidence/analyze.ts): route-handler · Evidence analysis endpoint · `pages/api/evidence/analyze.ts`
- [Image API](https://github.com/null-spectra/cognichain/blob/main/pages/api/evidence/analyze-image.ts): route-handler · Image interpretation endpoint · `pages/api/evidence/analyze-image.ts`
- [Chat API](https://github.com/null-spectra/cognichain/blob/main/pages/api/chat/generate.ts): route-handler · AI response generation · `pages/api/chat/generate.ts`

### Data

Realtime database schema and access control

- [Schema](https://github.com/null-spectra/cognichain/blob/main/instant.schema.ts): database-schema · Cases, evidence, logs, files · `instant.schema.ts`
- [Permissions](https://github.com/null-spectra/cognichain/blob/main/instant.perms.ts): access-control · Database authorization rules · `instant.perms.ts`
- [DB Clients](https://github.com/null-spectra/cognichain/blob/main/lib/db.ts): db-access · Client and admin database access · `lib/db.ts`

### Integrations

External AI and blockchain services

- [Blockchain](https://github.com/null-spectra/cognichain/blob/main/lib/blockchain.ts): eth-integration · Evidence anchoring to opBNB · `lib/blockchain.ts`

### Support

Shared utilities and app-wide styling

- [Hash Utils](https://github.com/null-spectra/cognichain/blob/main/lib/hash.ts): utility · Integrity hashing helpers · `lib/hash.ts`
- [ID Utils](https://github.com/null-spectra/cognichain/blob/main/lib/id.ts): utility · Stable identifier helpers · `lib/id.ts`

## Connections

- Dashboard → Cases API: load cases · Dashboard fetches case data
- Dashboard → Blockchain Feed: show feed · Dashboard surfaces on-chain activity
- Login → Permissions: authz · Login participates in access control
- Create Case → Cases API: create · Creates new cases through the API
- Case Detail → Cases API: load/update · Reads and updates case records
- Case Detail → Evidence API: manage evidence · Uploads and retrieves evidence
- Case Detail → Chat Window: embed chat · Case view contains AI chat interaction
- Case Detail → Blockchain Feed: show proof · Case view shows anchoring history
- Chat Window → Chat API: send prompt · Chat UI calls generation endpoint
- Cases API → Schema: persist cases · Case data is stored in the realtime schema
- Status API → Schema: update status · Status changes are written to the database
- Status API → Permissions: enforce access · Status updates are permission-gated
- Evidence API → Schema: persist evidence · Evidence metadata and file refs are stored
- Evidence API → Hash Utils: hash file · Evidence handling computes integrity hashes
- Evidence API → ID Utils: assign ids · Evidence records use stable identifiers
- Analyze API → Blockchain: anchor result · Analysis can feed blockchain verification
- Analyze API → Schema: save findings · Derived analysis is stored with evidence
- Image API → Schema: save vision data · Image analysis results are persisted
- Chat API → Schema: read context · Chat generation uses case and evidence context
- Schema → Permissions: guard data · Schema works with permissions for role-based access
- DB Clients → Schema: connect · Client and admin helpers access the schema
- DB Clients → Permissions: apply rules · Database access is governed by permissions
- Blockchain → Hash Utils: verify hash · Anchoring depends on evidence hashes
- Blockchain → Blockchain Feed: surface txs · Transaction history is shown in the UI
- Theme UI → Dashboard: style app · Global theming applies across routes