# subhasundardass/nodra-workspace architecture

> Architecture diagram of the GitHub repository subhasundardass/nodra-workspace, 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/subhasundardass/nodra-workspace
- Repository: https://github.com/subhasundardass/nodra-workspace

## Overview

Nodra is a TypeScript data/application framework, with `apps/todo` as its TanStack Start example application. The main documented workflow is a user interacting with the app UI, which invokes server functions in-process; the app initializes Nodra and uses its ORM against PostgreSQL to handle documents. The framework also provides metadata and lifecycle processing, permissions, views, reporting, file storage, jobs, workflows, events, and app-scoped CLI capabilities. Workflow links follow README documentation; unsampled implementation details are not expanded into unsupported call edges.

Main entry points: [`packages/nodra/src/orm/crud.ts`](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/orm/crud.ts) (ORM CRUD), [`packages/nodra/src/database/connection.ts`](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/database/connection.ts) (PostgreSQL), [`apps/todo/src/server/methods.ts`](https://github.com/subhasundardass/nodra-workspace/blob/main/apps/todo/src/server/methods.ts) (Server methods), [`apps/todo/src/server/auth.ts`](https://github.com/subhasundardass/nodra-workspace/blob/main/apps/todo/src/server/auth.ts) (Function auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Todo application"]
  node_ui["Todo UI routes<br/>[index.tsx]"]
  node_server["Server methods<br/>[methods.ts]"]
  node_auth["Function auth<br/>[auth.ts]"]
  node_appinit["Nodra app<br/>[nodra-app.ts]"]
end

subgraph group_core["Document framework"]
  node_doctype["DocType registry<br/>[registry.ts]"]
  node_document["Documents and validation<br/>[document.ts]"]
  node_orm["ORM CRUD<br/>[crud.ts]"]
  node_permissions["Permissions<br/>[permission.ts]"]
  node_hooks["Hooks and events<br/>[registry.ts]"]
end

subgraph group_extensions["Framework capabilities"]
  node_workflow["Workflow execution<br/>[executor.ts]"]
  node_views["View service<br/>[service.ts]"]
  node_reports["Reports<br/>[executor.ts]"]
  node_advanced["Search and export<br/>[advanced-query.ts]"]
  node_files["File storage<br/>[storage.ts]"]
  node_jobs["Job worker<br/>[worker.ts]"]
  node_cli["App CLI commands<br/>[app-commands.ts]"]
end

subgraph group_runtime["Persistence"]
  node_db[("PostgreSQL<br/>[connection.ts]")]
  node_query["SQL query builder<br/>[query-builder.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_ui
node_ui -->|"invokes functions"| node_server
node_server -->|"uses middleware"| node_auth
node_server -->|"gets app"| node_appinit
node_appinit -->|"loads metadata"| node_doctype
node_server -->|"calls CRUD"| node_orm
node_orm -->|"creates and updates"| node_document
node_orm -->|"uses metadata"| node_doctype
node_orm -->|"queries"| node_db
node_auth -->|"checks access"| node_permissions
node_auth -->|"loads user and roles"| node_orm
node_orm -->|"builds SQL"| node_query
node_query -->|"executes queries"| node_db
node_document -->|"runs lifecycle hooks"| node_hooks
node_workflow -->|"executes transitions"| node_document
node_views -->|"validates views"| node_doctype
node_reports -->|"runs report queries"| node_db
node_advanced -->|"searches and exports"| node_db
node_jobs -.->|"queue persistence"| node_db
node_cli -.->|"runs migrations"| node_db

click node_ui "https://github.com/subhasundardass/nodra-workspace/blob/main/apps/todo/src/routes/index.tsx"
click node_server "https://github.com/subhasundardass/nodra-workspace/blob/main/apps/todo/src/server/methods.ts"
click node_auth "https://github.com/subhasundardass/nodra-workspace/blob/main/apps/todo/src/server/auth.ts"
click node_appinit "https://github.com/subhasundardass/nodra-workspace/blob/main/apps/todo/src/server/nodra-app.ts"
click node_doctype "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/core/doctype/registry.ts"
click node_document "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/core/document/document.ts"
click node_orm "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/orm/crud.ts"
click node_permissions "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/permissions/permission.ts"
click node_hooks "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/hooks/registry.ts"
click node_workflow "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/workflow/executor.ts"
click node_views "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/core/view/service.ts"
click node_reports "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/reports/executor.ts"
click node_advanced "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/api/advanced-query.ts"
click node_files "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/files/storage.ts"
click node_jobs "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/jobs/worker.ts"
click node_db "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/database/connection.ts"
click node_query "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/database/query-builder.ts"
click node_cli "https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/cli/app-commands.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_ui,node_server,node_auth,node_appinit,node_user toneBlue
class node_doctype,node_document,node_orm,node_permissions,node_hooks toneAmber
class node_workflow,node_views,node_reports,node_advanced,node_files,node_jobs,node_cli toneMint
class node_db,node_query toneRose
```

## Components

### Todo application

- [Todo UI routes](https://github.com/subhasundardass/nodra-workspace/blob/main/apps/todo/src/routes/index.tsx): `apps/todo/src/routes/index.tsx`
- [Server methods](https://github.com/subhasundardass/nodra-workspace/blob/main/apps/todo/src/server/methods.ts): `apps/todo/src/server/methods.ts`
- [Function auth](https://github.com/subhasundardass/nodra-workspace/blob/main/apps/todo/src/server/auth.ts): `apps/todo/src/server/auth.ts`
- [Nodra app](https://github.com/subhasundardass/nodra-workspace/blob/main/apps/todo/src/server/nodra-app.ts): `apps/todo/src/server/nodra-app.ts`

### Document framework

- [DocType registry](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/core/doctype/registry.ts): `packages/nodra/src/core/doctype/registry.ts`
- [Documents and validation](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/core/document/document.ts): `packages/nodra/src/core/document/document.ts`
- [ORM CRUD](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/orm/crud.ts): `packages/nodra/src/orm/crud.ts`
- [Permissions](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/permissions/permission.ts): `packages/nodra/src/permissions/permission.ts`
- [Hooks and events](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/hooks/registry.ts): `packages/nodra/src/hooks/registry.ts`

### Framework capabilities

- [Workflow execution](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/workflow/executor.ts): `packages/nodra/src/workflow/executor.ts`
- [View service](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/core/view/service.ts): `packages/nodra/src/core/view/service.ts`
- [Reports](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/reports/executor.ts): `packages/nodra/src/reports/executor.ts`
- [Search and export](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/api/advanced-query.ts): `packages/nodra/src/api/advanced-query.ts`
- [File storage](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/files/storage.ts): `packages/nodra/src/files/storage.ts`
- [Job worker](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/jobs/worker.ts): `packages/nodra/src/jobs/worker.ts`
- [App CLI commands](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/cli/app-commands.ts): `packages/nodra/src/cli/app-commands.ts`

### Persistence

- [PostgreSQL](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/database/connection.ts): `packages/nodra/src/database/connection.ts`
- [SQL query builder](https://github.com/subhasundardass/nodra-workspace/blob/main/packages/nodra/src/database/query-builder.ts): `packages/nodra/src/database/query-builder.ts`

### Other components

- **User**

## Connections

- User → Todo UI routes: uses
- Todo UI routes → Server methods: invokes functions
- Server methods → Function auth: uses middleware
- Server methods → Nodra app: gets app
- Nodra app → DocType registry: loads metadata
- Server methods → ORM CRUD: calls CRUD
- ORM CRUD → Documents and validation: creates and updates
- ORM CRUD → DocType registry: uses metadata
- ORM CRUD → PostgreSQL: queries
- Function auth → Permissions: checks access
- Function auth → ORM CRUD: loads user and roles
- ORM CRUD → SQL query builder: builds SQL
- SQL query builder → PostgreSQL: executes queries
- Documents and validation → Hooks and events: runs lifecycle hooks
- Workflow execution → Documents and validation: executes transitions
- View service → DocType registry: validates views
- Reports → PostgreSQL: runs report queries
- Search and export → PostgreSQL: searches and exports
- Job worker → PostgreSQL: queue persistence
- App CLI commands → PostgreSQL: runs migrations