# liam-hq/liam architecture

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

- Interactive diagram: https://gitdiagram.com/liam-hq/liam
- Repository: https://github.com/liam-hq/liam

## Overview

Liam ERD turns database schemas into interactive entity-relationship diagrams, with public URL viewing, a CLI for private/local schemas, and a hosted collaborative design-session workflow. The principal hosted flow runs from a user prompt through streamed agent work to versioned schema output and an ERD. The graph also includes project/repository setup, organization management, and the shared diagram renderer. Several connections are supported only by README statements or the source index; unsampled implementation details are not inferred.

Main entry points: [`frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx`](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx) (Design session), [`frontend/packages/erd-core/src`](https://github.com/liam-hq/liam/tree/main/frontend/packages/erd-core/src) (Interactive ERD renderer), [`frontend/packages/cli/src/App.tsx`](https://github.com/liam-hq/liam/blob/main/frontend/packages/cli/src/App.tsx) (CLI viewer), [`frontend/apps/app/components/SessionDetailPage/hooks/useStream`](https://github.com/liam-hq/liam/tree/main/frontend/apps/app/components/SessionDetailPage/hooks/useStream) (Stream controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Product entry points"]
  node_public_url["Public ERD URL<br/>[page.tsx]"]
  node_cli["CLI viewer<br/>[App.tsx]"]
end

subgraph group_hosted["Hosted design sessions"]
  node_hosted_session["Design session"]
  node_chat["Session chat<br/>[Chat.tsx]"]
  node_stream_hook["Stream controller"]
  node_stream_api["Chat stream API<br/>[route.ts]"]
  node_replay_api["Chat replay API<br/>[route.ts]"]
  node_agent["Agent stream processing<br/>[handlers.ts]"]
  node_message_chunks["Message chunk assembly"]
  node_session_output["Session output<br/>[Output.tsx]"]
  node_realtime_versions["Realtime schema versions"]
  node_database[("Application database<br/>[server.ts]")]
end

subgraph group_diagram["Schema and diagrams"]
  node_schema_model["Schema parsing"]
  node_erd_renderer["Interactive ERD renderer"]
  node_erd_query_state["Diagram navigation state"]
  node_pglite["SQL execution"]
end

subgraph group_workspace["Projects and teams"]
  node_projects["Project management<br/>[route.ts]"]
  node_project_setup["Repository setup<br/>[ProjectNewPage.tsx]"]
  node_org_members["Organization members"]
  node_member_items["Member and invite items<br/>[MemberItem.tsx]"]
  node_invite_items["Invitation items<br/>[InvitationItem.tsx]"]
end

node_user(("User"))
node_schema_source["Database schema"]

node_user -->|"opens schema link"| node_public_url
node_schema_source -->|"renders from schema"| node_public_url
node_user -->|"starts private viewer"| node_cli
node_cli -->|"loads schema JSON"| node_schema_source
node_cli -->|"renders diagram"| node_erd_renderer
node_user -.->|"opens session"| node_hosted_session
node_hosted_session -->|"renders chat"| node_chat
node_hosted_session -->|"starts or replays"| node_stream_hook
node_stream_hook -.->|"streams messages"| node_stream_api
node_stream_hook -.->|"replays workflow"| node_replay_api
node_stream_api -->|"reads session data"| node_database
node_replay_api -->|"reads session data"| node_database
node_agent -->|"assembles chunks"| node_message_chunks
node_hosted_session -->|"renders results"| node_session_output
node_hosted_session -->|"tracks versions"| node_realtime_versions
node_session_output -.->|"displays schema"| node_erd_renderer
node_schema_source -->|"reverse engineers"| node_schema_model
node_schema_model -->|"provides schema"| node_erd_renderer
node_erd_renderer -->|"updates diagram state"| node_erd_query_state
node_user -.->|"runs SQL"| node_pglite
node_user -.->|"manages projects"| node_projects
node_projects -.->|"configures repositories"| node_project_setup
node_org_members -->|"renders members"| node_member_items
node_org_members -->|"renders invitations"| node_invite_items

click node_public_url "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/app/erd/p/%5B...slug%5D/page.tsx"
click node_cli "https://github.com/liam-hq/liam/blob/main/frontend/packages/cli/src/App.tsx"
click node_hosted_session "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx"
click node_chat "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/SessionDetailPage/components/Chat/Chat.tsx"
click node_stream_hook "https://github.com/liam-hq/liam/tree/main/frontend/apps/app/components/SessionDetailPage/hooks/useStream"
click node_stream_api "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/app/api/chat/stream/route.ts"
click node_replay_api "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/app/api/chat/replay/route.ts"
click node_agent "https://github.com/liam-hq/liam/blob/main/frontend/internal-packages/agent/src/streaming/server/handlers.ts"
click node_message_chunks "https://github.com/liam-hq/liam/blob/main/frontend/internal-packages/agent/src/streaming/core/MessageTupleManager.ts"
click node_session_output "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/SessionDetailPage/components/Output/Output.tsx"
click node_realtime_versions "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/SessionDetailPage/hooks/useRealtimeVersionsWithSchema/useRealtimeVersionsWithSchema.ts"
click node_database "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/libs/db/server.ts"
click node_schema_model "https://github.com/liam-hq/liam/tree/main/frontend/packages/schema/src"
click node_erd_renderer "https://github.com/liam-hq/liam/tree/main/frontend/packages/erd-core/src"
click node_erd_query_state "https://github.com/liam-hq/liam/blob/main/frontend/packages/erd-core/src/features/erd/components/ERDContent/hooks/useQueryParamsChanged.ts"
click node_pglite "https://github.com/liam-hq/liam/blob/main/frontend/internal-packages/pglite-server/src/PGliteInstanceManager.ts"
click node_projects "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/app/api/projects/route.ts"
click node_project_setup "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/ProjectNewPage/ProjectNewPage.tsx"
click node_org_members "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/OrganizationMembersPage/components/ClientSearchWrapper/ClientSearchWrapper.tsx"
click node_member_items "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/OrganizationMembersPage/components/MemberItem/MemberItem.tsx"
click node_invite_items "https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/OrganizationMembersPage/components/InvitationItem/InvitationItem.tsx"

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_public_url,node_cli,node_user toneBlue
class node_hosted_session,node_chat,node_stream_hook,node_stream_api,node_replay_api,node_agent,node_message_chunks,node_session_output,node_realtime_versions,node_database,node_schema_source toneAmber
class node_schema_model,node_erd_renderer,node_erd_query_state,node_pglite toneMint
class node_projects,node_project_setup,node_org_members,node_member_items,node_invite_items toneRose
```

## Components

### Product entry points

- [Public ERD URL](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/app/erd/p/%5B...slug%5D/page.tsx): `frontend/apps/app/app/erd/p/[...slug]/page.tsx`
- [CLI viewer](https://github.com/liam-hq/liam/blob/main/frontend/packages/cli/src/App.tsx): `frontend/packages/cli/src/App.tsx`

### Hosted design sessions

- [Design session](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx): `frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx`
- [Session chat](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/SessionDetailPage/components/Chat/Chat.tsx): `frontend/apps/app/components/SessionDetailPage/components/Chat/Chat.tsx`
- [Stream controller](https://github.com/liam-hq/liam/tree/main/frontend/apps/app/components/SessionDetailPage/hooks/useStream): `frontend/apps/app/components/SessionDetailPage/hooks/useStream`
- [Chat stream API](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/app/api/chat/stream/route.ts): `frontend/apps/app/app/api/chat/stream/route.ts`
- [Chat replay API](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/app/api/chat/replay/route.ts): `frontend/apps/app/app/api/chat/replay/route.ts`
- [Agent stream processing](https://github.com/liam-hq/liam/blob/main/frontend/internal-packages/agent/src/streaming/server/handlers.ts): `frontend/internal-packages/agent/src/streaming/server/handlers.ts`
- [Message chunk assembly](https://github.com/liam-hq/liam/blob/main/frontend/internal-packages/agent/src/streaming/core/MessageTupleManager.ts): `frontend/internal-packages/agent/src/streaming/core/MessageTupleManager.ts`
- [Session output](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/SessionDetailPage/components/Output/Output.tsx): `frontend/apps/app/components/SessionDetailPage/components/Output/Output.tsx`
- [Realtime schema versions](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/SessionDetailPage/hooks/useRealtimeVersionsWithSchema/useRealtimeVersionsWithSchema.ts): `frontend/apps/app/components/SessionDetailPage/hooks/useRealtimeVersionsWithSchema/useRealtimeVersionsWithSchema.ts`
- [Application database](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/libs/db/server.ts): `frontend/apps/app/libs/db/server.ts`

### Schema and diagrams

- [Schema parsing](https://github.com/liam-hq/liam/tree/main/frontend/packages/schema/src): `frontend/packages/schema/src`
- [Interactive ERD renderer](https://github.com/liam-hq/liam/tree/main/frontend/packages/erd-core/src): `frontend/packages/erd-core/src`
- [Diagram navigation state](https://github.com/liam-hq/liam/blob/main/frontend/packages/erd-core/src/features/erd/components/ERDContent/hooks/useQueryParamsChanged.ts): `frontend/packages/erd-core/src/features/erd/components/ERDContent/hooks/useQueryParamsChanged.ts`
- [SQL execution](https://github.com/liam-hq/liam/blob/main/frontend/internal-packages/pglite-server/src/PGliteInstanceManager.ts): `frontend/internal-packages/pglite-server/src/PGliteInstanceManager.ts`

### Projects and teams

- [Project management](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/app/api/projects/route.ts): `frontend/apps/app/app/api/projects/route.ts`
- [Repository setup](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/ProjectNewPage/ProjectNewPage.tsx): `frontend/apps/app/components/ProjectNewPage/ProjectNewPage.tsx`
- [Organization members](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/OrganizationMembersPage/components/ClientSearchWrapper/ClientSearchWrapper.tsx): `frontend/apps/app/components/OrganizationMembersPage/components/ClientSearchWrapper/ClientSearchWrapper.tsx`
- [Member and invite items](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/OrganizationMembersPage/components/MemberItem/MemberItem.tsx): `frontend/apps/app/components/OrganizationMembersPage/components/MemberItem/MemberItem.tsx`
- [Invitation items](https://github.com/liam-hq/liam/blob/main/frontend/apps/app/components/OrganizationMembersPage/components/InvitationItem/InvitationItem.tsx): `frontend/apps/app/components/OrganizationMembersPage/components/InvitationItem/InvitationItem.tsx`

### Other components

- **User**
- **Database schema**

## Connections

- User → Public ERD URL: opens schema link (evidence: `README.md`)
- Database schema → Public ERD URL: renders from schema (evidence: `README.md`)
- User → CLI viewer: starts private viewer (evidence: `README.md`)
- CLI viewer → Database schema: loads schema JSON (evidence: `frontend/packages/cli/src/App.tsx`)
- CLI viewer → Interactive ERD renderer: renders diagram (evidence: `frontend/packages/cli/src/App.tsx`)
- User → Design session: opens session
- Design session → Session chat: renders chat (evidence: `frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx`)
- Design session → Stream controller: starts or replays (evidence: `frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx`)
- Stream controller → Chat stream API: streams messages
- Stream controller → Chat replay API: replays workflow
- Chat stream API → Application database: reads session data (evidence: `frontend/apps/app/app/api/chat/stream/route.ts`)
- Chat replay API → Application database: reads session data (evidence: `frontend/apps/app/app/api/chat/replay/route.ts`)
- Agent stream processing → Message chunk assembly: assembles chunks (evidence: `frontend/internal-packages/agent/src/streaming/server/handlers.ts`)
- Design session → Session output: renders results (evidence: `frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx`)
- Design session → Realtime schema versions: tracks versions (evidence: `frontend/apps/app/components/SessionDetailPage/SessionDetailPageClient.tsx`)
- Session output → Interactive ERD renderer: displays schema
- Database schema → Schema parsing: reverse engineers (evidence: `README.md`)
- Schema parsing → Interactive ERD renderer: provides schema (evidence: `README.md`)
- Interactive ERD renderer → Diagram navigation state: updates diagram state (evidence: `frontend/packages/erd-core/src/features/erd/components/ERDContent/hooks/useQueryParamsChanged.ts`)
- User → SQL execution: runs SQL
- User → Project management: manages projects
- Project management → Repository setup: configures repositories
- Organization members → Member and invite items: renders members (evidence: `frontend/apps/app/components/OrganizationMembersPage/components/ClientSearchWrapper/ClientSearchWrapper.tsx`)
- Organization members → Invitation items: renders invitations (evidence: `frontend/apps/app/components/OrganizationMembersPage/components/ClientSearchWrapper/ClientSearchWrapper.tsx`)
