# ouzayr/utilities architecture

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

- Interactive diagram: https://gitdiagram.com/ouzayr/utilities
- Repository: https://github.com/ouzayr/utilities

## Overview

The tree contains several independent products rather than one integrated application; no README was provided to establish a single product or cross-project wiring. The graph focuses on the substantial projects represented in the tree and sampled source: code-cartographer, REFRAG, DailyPlanner, and sql-utility. Code Cartographer supports repository scanning and analysis views; REFRAG manages documents and answers retrieval-grounded queries; DailyPlanner manages dated tasks; sql-utility provides database inspection and checks. Links among unsampled subsystems are omitted where their callers could not be verified.

Main entry points: [`REFRAG/backend/app/services/refrag_service.py`](https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/refrag_service.py) (Retrieval and refinement), [`REFRAG/backend/app/api/routes.py`](https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/api/routes.py) (Document and query API), [`code-cartographer/apps/api/Db/AppDbContext.cs`](https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/api/Db/AppDbContext.cs) (Analysis store), [`REFRAG/frontend/src/app/documents/page.tsx`](https://github.com/ouzayr/utilities/blob/main/REFRAG/frontend/src/app/documents/page.tsx) (Document screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cartographer["Code Cartographer"]
  node_ccweb["Analysis views<br/>[app.routes.ts]"]
  node_ccapi["API endpoints"]
  node_ccdb[("Analysis store<br/>[AppDbContext.cs]")]
  node_dotnet[".NET scanner<br/>[SolutionScanner.cs]"]
  node_angularscan["Angular scanner<br/>[scanner.ts]"]
  node_diff["Scan comparison<br/>[DiffEngine.cs]"]
  node_flow["Dependency traversal<br/>[FlowEngine.cs]"]
end

subgraph group_refrag["REFRAG"]
  node_refragui["Document screens<br/>[page.tsx]"]
  node_refragapi["Document and query API<br/>[routes.py]"]
  node_docservice["Document service"]
  node_refragcore["Retrieval and refinement<br/>[refrag_service.py]"]
  node_chromadb[("Vector index<br/>[chroma_service.py]")]
  node_embeddings["Embeddings"]
  node_llm["Language model client<br/>[llm_service.py]"]
end

subgraph group_planner["DailyPlanner"]
  node_plannerui["Task views<br/>[App.tsx]"]
  node_taskstore["Task client store<br/>[storage.ts]"]
  node_plannerapi["Task routes<br/>[routes.ts]"]
  node_taskstorage["Task persistence<br/>[storage.ts]"]
  node_taskdb[("Task database<br/>[db.ts]")]
end

subgraph group_sqlutil["SQL Utility"]
  node_sqlapi["SQL API<br/>[main.py]"]
  node_sqlroutes["SQL endpoints"]
  node_checks["Schema checks<br/>[engine.py]"]
  node_schema["Schema model<br/>[schema_model.py]"]
end

node_engineer(("Engineer"))
node_ollama["Ollama"]

node_engineer -->|"uses views"| node_ccweb
node_ccdb -->|"reads scans"| node_diff
node_ccdb -->|"reads graph"| node_flow
node_engineer -->|"uses screens"| node_refragui
node_refragui -->|"requests data"| node_refragapi
node_refragapi -->|"manages documents"| node_docservice
node_refragapi -->|"dispatches queries"| node_refragcore
node_refragcore -->|"retrieves documents"| node_chromadb
node_refragcore -->|"encodes and scores"| node_embeddings
node_refragcore -->|"generates answers"| node_llm
node_llm -->|"calls API"| node_ollama
node_engineer -->|"manages tasks"| node_plannerui
node_plannerui -->|"uses task store"| node_taskstore
node_taskstore -->|"sends requests"| node_plannerapi
node_plannerapi -->|"persists tasks"| node_taskstorage
node_taskstorage -->|"queries database"| node_taskdb
node_engineer -->|"inspects databases"| node_sqlapi
node_sqlapi -->|"mounts endpoints"| node_sqlroutes
node_checks -->|"checks schema"| node_schema

click node_ccweb "https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/web/src/app/app.routes.ts"
click node_ccapi "https://github.com/ouzayr/utilities/tree/main/code-cartographer/apps/api/Endpoints"
click node_ccdb "https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/api/Db/AppDbContext.cs"
click node_dotnet "https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/scanner-dotnet/SolutionScanner.cs"
click node_angularscan "https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/scanner-angular/src/scanner.ts"
click node_diff "https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/api/Diff/DiffEngine.cs"
click node_flow "https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/api/Flow/FlowEngine.cs"
click node_refragui "https://github.com/ouzayr/utilities/blob/main/REFRAG/frontend/src/app/documents/page.tsx"
click node_refragapi "https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/api/routes.py"
click node_docservice "https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/document_service.py"
click node_refragcore "https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/refrag_service.py"
click node_chromadb "https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/chroma_service.py"
click node_embeddings "https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/embedding_service.py"
click node_llm "https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/llm_service.py"
click node_plannerui "https://github.com/ouzayr/utilities/blob/main/DailyPlanner/client/src/App.tsx"
click node_taskstore "https://github.com/ouzayr/utilities/blob/main/DailyPlanner/client/src/lib/storage.ts"
click node_plannerapi "https://github.com/ouzayr/utilities/blob/main/DailyPlanner/server/routes.ts"
click node_taskstorage "https://github.com/ouzayr/utilities/blob/main/DailyPlanner/server/storage.ts"
click node_taskdb "https://github.com/ouzayr/utilities/blob/main/DailyPlanner/server/db.ts"
click node_sqlapi "https://github.com/ouzayr/utilities/blob/main/sql-utility/apps/api/sqlutil/main.py"
click node_sqlroutes "https://github.com/ouzayr/utilities/tree/main/sql-utility/apps/api/sqlutil/routes"
click node_checks "https://github.com/ouzayr/utilities/blob/main/sql-utility/apps/api/sqlutil/checks/engine.py"
click node_schema "https://github.com/ouzayr/utilities/blob/main/sql-utility/apps/api/sqlutil/introspect/schema_model.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_ccweb,node_ccapi,node_ccdb,node_dotnet,node_angularscan,node_diff,node_flow toneBlue
class node_refragui,node_refragapi,node_docservice,node_refragcore,node_chromadb,node_embeddings,node_llm toneAmber
class node_plannerui,node_taskstore,node_plannerapi,node_taskstorage,node_taskdb toneMint
class node_sqlapi,node_sqlroutes,node_checks,node_schema toneRose
class node_engineer,node_ollama toneIndigo
```

## Components

### Code Cartographer

- [Analysis views](https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/web/src/app/app.routes.ts): `code-cartographer/apps/web/src/app/app.routes.ts`
- [API endpoints](https://github.com/ouzayr/utilities/tree/main/code-cartographer/apps/api/Endpoints): `code-cartographer/apps/api/Endpoints`
- [Analysis store](https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/api/Db/AppDbContext.cs): `code-cartographer/apps/api/Db/AppDbContext.cs`
- [.NET scanner](https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/scanner-dotnet/SolutionScanner.cs): `code-cartographer/apps/scanner-dotnet/SolutionScanner.cs`
- [Angular scanner](https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/scanner-angular/src/scanner.ts): `code-cartographer/apps/scanner-angular/src/scanner.ts`
- [Scan comparison](https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/api/Diff/DiffEngine.cs): `code-cartographer/apps/api/Diff/DiffEngine.cs`
- [Dependency traversal](https://github.com/ouzayr/utilities/blob/main/code-cartographer/apps/api/Flow/FlowEngine.cs): `code-cartographer/apps/api/Flow/FlowEngine.cs`

### REFRAG

- [Document screens](https://github.com/ouzayr/utilities/blob/main/REFRAG/frontend/src/app/documents/page.tsx): `REFRAG/frontend/src/app/documents/page.tsx`
- [Document and query API](https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/api/routes.py): `REFRAG/backend/app/api/routes.py`
- [Document service](https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/document_service.py): `REFRAG/backend/app/services/document_service.py`
- [Retrieval and refinement](https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/refrag_service.py): `REFRAG/backend/app/services/refrag_service.py`
- [Vector index](https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/chroma_service.py): `REFRAG/backend/app/services/chroma_service.py`
- [Embeddings](https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/embedding_service.py): `REFRAG/backend/app/services/embedding_service.py`
- [Language model client](https://github.com/ouzayr/utilities/blob/main/REFRAG/backend/app/services/llm_service.py): `REFRAG/backend/app/services/llm_service.py`

### DailyPlanner

- [Task views](https://github.com/ouzayr/utilities/blob/main/DailyPlanner/client/src/App.tsx): `DailyPlanner/client/src/App.tsx`
- [Task client store](https://github.com/ouzayr/utilities/blob/main/DailyPlanner/client/src/lib/storage.ts): `DailyPlanner/client/src/lib/storage.ts`
- [Task routes](https://github.com/ouzayr/utilities/blob/main/DailyPlanner/server/routes.ts): `DailyPlanner/server/routes.ts`
- [Task persistence](https://github.com/ouzayr/utilities/blob/main/DailyPlanner/server/storage.ts): `DailyPlanner/server/storage.ts`
- [Task database](https://github.com/ouzayr/utilities/blob/main/DailyPlanner/server/db.ts): `DailyPlanner/server/db.ts`

### SQL Utility

- [SQL API](https://github.com/ouzayr/utilities/blob/main/sql-utility/apps/api/sqlutil/main.py): `sql-utility/apps/api/sqlutil/main.py`
- [SQL endpoints](https://github.com/ouzayr/utilities/tree/main/sql-utility/apps/api/sqlutil/routes): `sql-utility/apps/api/sqlutil/routes`
- [Schema checks](https://github.com/ouzayr/utilities/blob/main/sql-utility/apps/api/sqlutil/checks/engine.py): `sql-utility/apps/api/sqlutil/checks/engine.py`
- [Schema model](https://github.com/ouzayr/utilities/blob/main/sql-utility/apps/api/sqlutil/introspect/schema_model.py): `sql-utility/apps/api/sqlutil/introspect/schema_model.py`

### Other components

- **Engineer**
- **Ollama**

## Connections

- Engineer → Analysis views: uses views
- Analysis store → Scan comparison: reads scans
- Analysis store → Dependency traversal: reads graph
- Engineer → Document screens: uses screens
- Document screens → Document and query API: requests data
- Document and query API → Document service: manages documents
- Document and query API → Retrieval and refinement: dispatches queries
- Retrieval and refinement → Vector index: retrieves documents
- Retrieval and refinement → Embeddings: encodes and scores
- Retrieval and refinement → Language model client: generates answers
- Language model client → Ollama: calls API
- Engineer → Task views: manages tasks
- Task views → Task client store: uses task store
- Task client store → Task routes: sends requests
- Task routes → Task persistence: persists tasks
- Task persistence → Task database: queries database
- Engineer → SQL API: inspects databases
- SQL API → SQL endpoints: mounts endpoints
- Schema checks → Schema model: checks schema