null-spectra/cognichain

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.