# maxim-abuzarov/presight architecture

> Architecture diagram of the GitHub repository maxim-abuzarov/presight, 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/maxim-abuzarov/presight
- Repository: https://github.com/maxim-abuzarov/presight

## Overview

People Directory is a searchable, filterable directory with a React client, an Express API, and SQLite as its source of truth. The main workflow is: a person adjusts URL-synced search, filter, or sort state; the client requests paginated people and separately refreshed facet counts; the API validates requests and queries a shared filtered result set in SQLite; results and facets return to the interface. The graph also preserves database setup and data-seeding stages. Some links rely on the SOURCE INDEX or README because those implementation files were not excerpted.

Main entry points: [`client/src/App.tsx`](https://github.com/maxim-abuzarov/presight/blob/main/client/src/App.tsx) (Directory view), [`server/src/db/connection.ts`](https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/connection.ts) (SQLite database), [`server/src/db/seed.ts`](https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/seed.ts) (Dataset seeding), [`server/src/users/users.repository.ts`](https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.repository.ts) (User queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Directory client"]
  node_app["Directory view<br/>[App.tsx]"]
  node_filterstate["Filter state<br/>[useFilterState.ts]"]
  node_directoryhooks["Directory queries<br/>[useDirectory.ts]"]
  node_apiclient["API client<br/>[client.ts]"]
  node_search["Search control<br/>[SearchField.tsx]"]
  node_sort["Sort controls<br/>[SortControls.tsx]"]
  node_filters["Filter panels<br/>[FilterSidebar.tsx]"]
  node_activefilters["Active filters<br/>[ActiveFilters.tsx]"]
  node_userlist["Virtual user list<br/>[UserList.tsx]"]
  node_icons["Icons<br/>[Icon.tsx]"]
  node_spider["SpiderWeb view<br/>[SpiderWeb.tsx]"]
  node_states["Loading and errors<br/>[States.tsx]"]
  node_clienttypes["Client data types<br/>[types.ts]"]
end

subgraph group_api["API and domain"]
  node_routes["API routes<br/>[users.routes.ts]"]
  node_controller["Request handlers"]
  node_service["User service<br/>[users.service.ts]"]
  node_repository["User queries"]
  node_sqlfilters["Filter SQL<br/>[users.filters.ts]"]
  node_servertypes["User domain types<br/>[users.types.ts]"]
  node_appserver["HTTP application<br/>[app.ts]"]
  node_serverentry["Server startup<br/>[server.ts]"]
end

subgraph group_storage["SQLite storage"]
  node_database[("SQLite database<br/>[connection.ts]")]
  node_config["Runtime configuration<br/>[config.ts]"]
end

subgraph group_setup["Data initialization"]
  node_migrations["Schema migrations<br/>[migrate.ts]"]
  node_schema["Database schema<br/>[schema.ts]"]
  node_seed["Dataset seeding<br/>[seed.ts]"]
  node_datasets["Seed datasets<br/>[datasets.ts]"]
  node_seal["Database sealing<br/>[seal.ts]"]
end

node_person(("Person"))

node_person -->|"uses"| node_app
node_app -->|"reads state"| node_filterstate
node_app -->|"loads data"| node_directoryhooks
node_app -->|"renders"| node_search
node_app -->|"renders"| node_sort
node_app -->|"renders"| node_filters
node_app -->|"renders"| node_activefilters
node_app -->|"renders"| node_userlist
node_app -->|"loads lazily"| node_spider
node_app -->|"renders"| node_states
node_directoryhooks -->|"requests data"| node_apiclient
node_apiclient -->|"calls endpoints"| node_routes
node_apiclient -->|"uses response types"| node_clienttypes
node_routes -->|"dispatches"| node_controller
node_controller -->|"calls"| node_service
node_service -->|"delegates queries"| node_repository
node_repository -->|"builds filtered queries"| node_sqlfilters
node_repository -->|"queries"| node_database
node_repository -->|"uses domain types"| node_servertypes
node_appserver -->|"mounts API"| node_routes
node_serverentry -->|"starts"| node_appserver
node_serverentry -->|"runs before serving"| node_migrations
node_database -->|"reads settings"| node_config
node_migrations -->|"updates schema"| node_database
node_migrations -->|"applies"| node_schema
node_seed -->|"writes records"| node_database
node_seed -->|"loads records from"| node_datasets
node_seed -->|"ensures schema"| node_migrations
node_seal -->|"checkpoints and seals"| node_database
node_seed -->|"reads settings"| node_config
node_seal -->|"reads settings"| node_config

click node_app "https://github.com/maxim-abuzarov/presight/blob/main/client/src/App.tsx"
click node_filterstate "https://github.com/maxim-abuzarov/presight/blob/main/client/src/hooks/useFilterState.ts"
click node_directoryhooks "https://github.com/maxim-abuzarov/presight/blob/main/client/src/hooks/useDirectory.ts"
click node_apiclient "https://github.com/maxim-abuzarov/presight/blob/main/client/src/api/client.ts"
click node_search "https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/SearchField.tsx"
click node_sort "https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/SortControls.tsx"
click node_filters "https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/FilterSidebar.tsx"
click node_activefilters "https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/ActiveFilters.tsx"
click node_userlist "https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/UserList.tsx"
click node_icons "https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/Icon.tsx"
click node_spider "https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/SpiderWeb.tsx"
click node_states "https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/States.tsx"
click node_clienttypes "https://github.com/maxim-abuzarov/presight/blob/main/client/src/api/types.ts"
click node_routes "https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.routes.ts"
click node_controller "https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.controller.ts"
click node_service "https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.service.ts"
click node_repository "https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.repository.ts"
click node_sqlfilters "https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.filters.ts"
click node_servertypes "https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.types.ts"
click node_appserver "https://github.com/maxim-abuzarov/presight/blob/main/server/src/app.ts"
click node_serverentry "https://github.com/maxim-abuzarov/presight/blob/main/server/src/server.ts"
click node_database "https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/connection.ts"
click node_config "https://github.com/maxim-abuzarov/presight/blob/main/server/src/config.ts"
click node_migrations "https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/migrate.ts"
click node_schema "https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/schema.ts"
click node_seed "https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/seed.ts"
click node_datasets "https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/datasets.ts"
click node_seal "https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/seal.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,node_filterstate,node_directoryhooks,node_apiclient,node_search,node_sort,node_filters,node_activefilters,node_userlist,node_icons,node_spider,node_states,node_clienttypes toneBlue
class node_routes,node_controller,node_service,node_repository,node_sqlfilters,node_servertypes,node_appserver,node_serverentry toneAmber
class node_database,node_config toneMint
class node_migrations,node_schema,node_seed,node_datasets,node_seal toneRose
class node_person toneIndigo
```

## Components

### Directory client

- [Directory view](https://github.com/maxim-abuzarov/presight/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Filter state](https://github.com/maxim-abuzarov/presight/blob/main/client/src/hooks/useFilterState.ts): `client/src/hooks/useFilterState.ts`
- [Directory queries](https://github.com/maxim-abuzarov/presight/blob/main/client/src/hooks/useDirectory.ts): `client/src/hooks/useDirectory.ts`
- [API client](https://github.com/maxim-abuzarov/presight/blob/main/client/src/api/client.ts): `client/src/api/client.ts`
- [Search control](https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/SearchField.tsx): `client/src/components/SearchField.tsx`
- [Sort controls](https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/SortControls.tsx): `client/src/components/SortControls.tsx`
- [Filter panels](https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/FilterSidebar.tsx): `client/src/components/FilterSidebar.tsx`
- [Active filters](https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/ActiveFilters.tsx): `client/src/components/ActiveFilters.tsx`
- [Virtual user list](https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/UserList.tsx): `client/src/components/UserList.tsx`
- [Icons](https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/Icon.tsx): `client/src/components/Icon.tsx`
- [SpiderWeb view](https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/SpiderWeb.tsx): `client/src/components/SpiderWeb.tsx`
- [Loading and errors](https://github.com/maxim-abuzarov/presight/blob/main/client/src/components/States.tsx): `client/src/components/States.tsx`
- [Client data types](https://github.com/maxim-abuzarov/presight/blob/main/client/src/api/types.ts): `client/src/api/types.ts`

### API and domain

- [API routes](https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.routes.ts): `server/src/users/users.routes.ts`
- [Request handlers](https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.controller.ts): `server/src/users/users.controller.ts`
- [User service](https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.service.ts): `server/src/users/users.service.ts`
- [User queries](https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.repository.ts): `server/src/users/users.repository.ts`
- [Filter SQL](https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.filters.ts): `server/src/users/users.filters.ts`
- [User domain types](https://github.com/maxim-abuzarov/presight/blob/main/server/src/users/users.types.ts): `server/src/users/users.types.ts`
- [HTTP application](https://github.com/maxim-abuzarov/presight/blob/main/server/src/app.ts): `server/src/app.ts`
- [Server startup](https://github.com/maxim-abuzarov/presight/blob/main/server/src/server.ts): `server/src/server.ts`

### SQLite storage

- [SQLite database](https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/connection.ts): `server/src/db/connection.ts`
- [Runtime configuration](https://github.com/maxim-abuzarov/presight/blob/main/server/src/config.ts): `server/src/config.ts`

### Data initialization

- [Schema migrations](https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/migrate.ts): `server/src/db/migrate.ts`
- [Database schema](https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/schema.ts): `server/src/db/schema.ts`
- [Dataset seeding](https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/seed.ts): `server/src/db/seed.ts`
- [Seed datasets](https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/datasets.ts): `server/src/db/datasets.ts`
- [Database sealing](https://github.com/maxim-abuzarov/presight/blob/main/server/src/db/seal.ts): `server/src/db/seal.ts`

### Other components

- **Person**

## Connections

- Person → Directory view: uses
- Directory view → Filter state: reads state (evidence: `client/src/App.tsx`)
- Directory view → Directory queries: loads data (evidence: `client/src/App.tsx`)
- Directory view → Search control: renders (evidence: `client/src/App.tsx`)
- Directory view → Sort controls: renders (evidence: `client/src/App.tsx`)
- Directory view → Filter panels: renders (evidence: `client/src/App.tsx`)
- Directory view → Active filters: renders (evidence: `client/src/App.tsx`)
- Directory view → Virtual user list: renders (evidence: `client/src/App.tsx`)
- Directory view → SpiderWeb view: loads lazily (evidence: `client/src/App.tsx`)
- Directory view → Loading and errors: renders (evidence: `client/src/App.tsx`)
- Directory queries → API client: requests data (evidence: `client/src/hooks/useDirectory.ts`)
- API client → API routes: calls endpoints
- API client → Client data types: uses response types (evidence: `client/src/api/client.ts`)
- API routes → Request handlers: dispatches (evidence: `server/src/users/users.routes.ts`)
- Request handlers → User service: calls (evidence: `server/src/users/users.controller.ts`)
- User service → User queries: delegates queries (evidence: `server/src/users/users.service.ts`)
- User queries → Filter SQL: builds filtered queries (evidence: `server/src/users/users.repository.ts`)
- User queries → SQLite database: queries (evidence: `server/src/users/users.repository.ts`)
- User queries → User domain types: uses domain types (evidence: `server/src/users/users.repository.ts`)
- HTTP application → API routes: mounts API (evidence: `server/src/app.ts`)
- Server startup → HTTP application: starts (evidence: `server/src/server.ts`)
- Server startup → Schema migrations: runs before serving (evidence: `server/src/server.ts`)
- SQLite database → Runtime configuration: reads settings (evidence: `server/src/db/connection.ts`)
- Schema migrations → SQLite database: updates schema (evidence: `server/src/db/migrate.ts`)
- Schema migrations → Database schema: applies (evidence: `server/src/db/migrate.ts`)
- Dataset seeding → SQLite database: writes records (evidence: `server/src/db/seed.ts`)
- Dataset seeding → Seed datasets: loads records from (evidence: `server/src/db/seed.ts`)
- Dataset seeding → Schema migrations: ensures schema (evidence: `server/src/db/seed.ts`)
- Database sealing → SQLite database: checkpoints and seals (evidence: `server/src/db/seal.ts`)
- Dataset seeding → Runtime configuration: reads settings (evidence: `server/src/db/seed.ts`)
- Database sealing → Runtime configuration: reads settings (evidence: `server/src/db/seal.ts`)
