# lawflow-boop/lawlink architecture

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

- Interactive diagram: https://gitdiagram.com/lawflow-boop/lawlink
- Repository: https://github.com/lawflow-boop/lawlink

## Overview

#### Purpose and runtime
LawLink is a self-hosted legal matter/project management system for small firms. It implements the operational path from intake and conflict checking through matter work, finance, archive, and export. It runs as a Next.js 16 App Router TypeScript application, backed by PostgreSQL 16 through Prisma and deployed locally or with Docker Compose. Core entry points are `src/app/layout.tsx`, authenticated application routing in `src/app/(app)/layout.tsx`, and container definitions in `Dockerfile` and `docker-compose.yml`.

#### Application boundary and access control
The UI is split into public authentication and authenticated application route groups. Credentials-based NextAuth sessions protect the app; server-side permissions are a separate authorization boundary. Relevant paths: `src/app/(auth)/login/page.tsx`, `src/app/api/auth/[...nextauth]/route.ts`, `src/lib/auth/options.ts`, `src/lib/permissions/index.ts`, and `src/proxy.ts`. Shared app navigation, notifications, search, and responsive shell are centralized in `src/components/layout/app-shell.tsx` and `src/components/layout/nav-config.ts`.

#### Persistence and core domain model
Prisma owns the relational schema and migration history, making PostgreSQL the system of record for users, firms, clients/contacts, intakes, matters, procedures/parties, documents, finance, approvals, reminders, notifications, and archival records. The schema and initial domain data live in `prisma/schema.prisma`, `prisma/seed.ts`, and `prisma/migrations/`. Application code accesses the database via `src/lib/prisma.ts`; server action modules form the domain-facing write/read layer rather than exposing generic CRUD APIs.

#### Intake-to-matter workflow
Intakes collect prospective work, support conflict review and cause recommendations, and can convert into formal matters. Matter lifecycle logic then coordinates the working record, team, parties, procedural information, notes, documents, tasks, reminders, and status transitions. Primary paths: `src/app/(app)/intakes/[id]/page.tsx`, `src/server/intakes/actions.ts`, `src/server/matters/actions.ts`, `src/server/matters/lifecycle.ts`, and `src/app/(app)/matters/[id]/page.tsx`. Conflict lookup is a dedicated domain algorithm at `src/server/conflicts/algorithm.ts`, surfaced by `src/app/(app)/conflicts/page.tsx`.

#### Matter operations, finance, and archive
The matter-detail screen is the principal workbench, composed as tabbed panels for procedural tracking, documents/folders, finance/invoices, approvals, preservation, and archive state. Financial records and invoice requests are handled separately from matter lifecycle operations. Closing/archival is guarded by checklist and review logic, then rendered/exported as an archive package. Paths: `src/app/(app)/matters/[id]/_components/matter-detail-tabs.tsx`, `src/server/finance/actions.ts`, `src/server/invoices/actions.ts`, `src/server/archive/actions.ts`, `src/server/archive/guard.ts`, and `src/app/api/archive/[matterId]/export/route.ts`.

#### Documents, storage, and AI/external integrations
Document and firm-file APIs enforce download/preview boundaries, while the storage abstraction supports local and S3-backed providers, validation, and encryption. Paths: `src/server/documents/actions.ts`, `src/app/api/documents/[id]/download/route.ts`, `src/lib/storage/provider.ts`, `src/lib/storage/s3.ts`, and `src/lib/storage/crypto.ts`. Optional AI workflows draft/review documents, parse pleadings/summons/express data, and recommend causes via configurable AI clients; YuanDian enterprise/case services are another external integration. Paths: `src/server/ai/actions.ts`, `src/server/ai/review-document.ts`, `src/lib/ai/client.ts`, and `src/lib/yuandian/client.ts`.

#### Scheduling, automation, reporting, and interchange
Schedule/tasks, reminders, notifications, dashboard metrics, reporting, imports, and XLSX exports are supporting operational flows over the same database. Scheduled jobs scan reminders, overdue archives, seal follow-ups, and audit cleanup; deployment must arrange execution of the scheduler/job layer. Paths: `src/server/cron/scheduler.ts`, `src/server/cron/jobs/scan-due-reminders.ts`, `src/server/reports/analytics.ts`, `src/app/api/reports/export/route.ts`, `src/server/imports/actions.ts`, and `src/app/api/matters/export/route.ts`.

Main entry points: [`src/lib/prisma.ts`](https://github.com/lawflow-boop/lawlink/blob/main/src/lib/prisma.ts) (Prisma data access), [`src/app/(app)/matters/[id]/page.tsx`](https://github.com/lawflow-boop/lawlink/blob/main/src/app/(app)/matters/%5Bid%5D/page.tsx) (Matter workbench), [`src/components/layout/app-shell.tsx`](https://github.com/lawflow-boop/lawlink/blob/main/src/components/layout/app-shell.tsx) (Authenticated app shell), [`src/server/matters/actions.ts`](https://github.com/lawflow-boop/lawlink/blob/main/src/server/matters/actions.ts) (Intake and matter actions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Application UI"]
  node_next_app["Next.js App Router<br/>application runtime<br/>[layout.tsx]"]
  node_auth_routes["Authentication<br/>public routes<br/>[page.tsx]"]
  node_app_shell["Authenticated app shell<br/>route shell<br/>[app-shell.tsx]"]
  node_access_control["Session and permissions<br/>security boundary<br/>[options.ts]"]
  node_intake_ui["Intake and conflict UI<br/>workflow screens<br/>[page.tsx]"]
  node_matter_workbench["Matter workbench<br/>detail screen<br/>[page.tsx]"]
end

subgraph group_domain["Domain workflows"]
  node_domain_actions{{"Intake and matter actions<br/>server actions<br/>[actions.ts]"}}
  node_matter_lifecycle["Matter lifecycle<br/>workflow logic<br/>[lifecycle.ts]"]
  node_conflict_engine["Conflict engine<br/>domain algorithm<br/>[algorithm.ts]"]
  node_finance_invoicing["Finance and invoices<br/>server actions<br/>[actions.ts]"]
  node_archive_workflow["Archive workflow<br/>guarded workflow"]
  node_archive_export["Archive export<br/>API route<br/>[route.ts]"]
  node_document_service["Document service<br/>server actions<br/>[actions.ts]"]
  node_scheduler["Scheduler and jobs<br/>automation<br/>[scheduler.ts]"]
  node_reporting_interchange["Reports, imports, exports<br/>operational services<br/>[analytics.ts]"]
end

subgraph group_platform["Platform and integrations"]
  node_ai_integrations["AI and YuanDian clients<br/>external integrations<br/>[client.ts]"]
  node_storage["File storage<br/>storage abstraction<br/>[provider.ts]"]
  node_prisma["Prisma data access<br/>database client<br/>[prisma.ts]"]
  node_postgres[("PostgreSQL system of record<br/>relational database<br/>[schema.prisma]")]
  node_deployment["Local and Docker deployment<br/>[docker-compose.yml]"]
end

node_next_app -->|"serves"| node_auth_routes
node_next_app -->|"hosts"| node_app_shell
node_auth_routes -->|"creates sessions via"| node_access_control
node_app_shell -->|"requires"| node_access_control
node_app_shell -->|"navigates to"| node_intake_ui
node_app_shell -->|"navigates to"| node_matter_workbench
node_intake_ui -->|"submits workflow actions"| node_domain_actions
node_intake_ui -->|"requests conflict review"| node_conflict_engine
node_matter_workbench -->|"operates matters through"| node_domain_actions
node_matter_workbench -->|"manages finance through"| node_finance_invoicing
node_matter_workbench -->|"manages files through"| node_document_service
node_matter_workbench -->|"closes through"| node_archive_workflow
node_domain_actions -->|"applies"| node_matter_lifecycle
node_domain_actions -->|"reads and writes"| node_prisma
node_conflict_engine -->|"searches records"| node_prisma
node_finance_invoicing -->|"persists records"| node_prisma
node_archive_workflow -->|"checks and records"| node_prisma
node_archive_workflow -->|"enables"| node_archive_export
node_document_service -->|"stores files in"| node_storage
node_document_service -->|"records metadata in"| node_prisma
node_scheduler -->|"scans operational records"| node_prisma
node_reporting_interchange -->|"queries operational data"| node_prisma
node_ai_integrations -.->|"drafts and reviews documents"| node_document_service
node_prisma -->|"connects to"| node_postgres
node_deployment -->|"runs"| node_next_app
node_deployment -.->|"must execute"| node_scheduler

click node_next_app "https://github.com/lawflow-boop/lawlink/blob/main/src/app/layout.tsx"
click node_auth_routes "https://github.com/lawflow-boop/lawlink/blob/main/src/app/(auth)/login/page.tsx"
click node_app_shell "https://github.com/lawflow-boop/lawlink/blob/main/src/components/layout/app-shell.tsx"
click node_access_control "https://github.com/lawflow-boop/lawlink/blob/main/src/lib/auth/options.ts"
click node_intake_ui "https://github.com/lawflow-boop/lawlink/blob/main/src/app/(app)/intakes/%5Bid%5D/page.tsx"
click node_matter_workbench "https://github.com/lawflow-boop/lawlink/blob/main/src/app/(app)/matters/%5Bid%5D/page.tsx"
click node_domain_actions "https://github.com/lawflow-boop/lawlink/blob/main/src/server/matters/actions.ts"
click node_matter_lifecycle "https://github.com/lawflow-boop/lawlink/blob/main/src/server/matters/lifecycle.ts"
click node_conflict_engine "https://github.com/lawflow-boop/lawlink/blob/main/src/server/conflicts/algorithm.ts"
click node_finance_invoicing "https://github.com/lawflow-boop/lawlink/blob/main/src/server/finance/actions.ts"
click node_archive_export "https://github.com/lawflow-boop/lawlink/blob/main/src/app/api/archive/%5BmatterId%5D/export/route.ts"
click node_document_service "https://github.com/lawflow-boop/lawlink/blob/main/src/server/documents/actions.ts"
click node_scheduler "https://github.com/lawflow-boop/lawlink/blob/main/src/server/cron/scheduler.ts"
click node_reporting_interchange "https://github.com/lawflow-boop/lawlink/blob/main/src/server/reports/analytics.ts"
click node_ai_integrations "https://github.com/lawflow-boop/lawlink/blob/main/src/lib/ai/client.ts"
click node_storage "https://github.com/lawflow-boop/lawlink/blob/main/src/lib/storage/provider.ts"
click node_prisma "https://github.com/lawflow-boop/lawlink/blob/main/src/lib/prisma.ts"
click node_postgres "https://github.com/lawflow-boop/lawlink/blob/main/prisma/schema.prisma"
click node_deployment "https://github.com/lawflow-boop/lawlink/blob/main/docker-compose.yml"

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_next_app,node_auth_routes,node_app_shell,node_access_control,node_intake_ui,node_matter_workbench toneBlue
class node_domain_actions,node_matter_lifecycle,node_conflict_engine,node_finance_invoicing,node_archive_workflow,node_archive_export,node_document_service,node_scheduler,node_reporting_interchange toneAmber
class node_ai_integrations,node_storage,node_prisma,node_postgres,node_deployment toneMint
```

## Components

### Application UI

Public and authenticated Next.js route groups.

- [Next.js App Router](https://github.com/lawflow-boop/lawlink/blob/main/src/app/layout.tsx): application runtime · Root layout hosts the self-managed legal operations application. · `src/app/layout.tsx`
- [Authentication](https://github.com/lawflow-boop/lawlink/blob/main/src/app/(auth)/login/page.tsx): public routes · Credentials login and NextAuth session endpoint. · `src/app/(auth)/login/page.tsx`
- [Authenticated app shell](https://github.com/lawflow-boop/lawlink/blob/main/src/components/layout/app-shell.tsx): route shell · Provides navigation, search, notifications, and responsive application layout. · `src/components/layout/app-shell.tsx`
- [Session and permissions](https://github.com/lawflow-boop/lawlink/blob/main/src/lib/auth/options.ts): security boundary · Separates NextAuth authentication from server-side authorization. · `src/lib/auth/options.ts`
- [Intake and conflict UI](https://github.com/lawflow-boop/lawlink/blob/main/src/app/(app)/intakes/%5Bid%5D/page.tsx): workflow screens · Captures prospective work and surfaces conflict review. · `src/app/(app)/intakes/[id]/page.tsx`
- [Matter workbench](https://github.com/lawflow-boop/lawlink/blob/main/src/app/(app)/matters/%5Bid%5D/page.tsx): detail screen · Tabbed operational view for lifecycle, procedure, documents, finance, approvals, and archive. · `src/app/(app)/matters/[id]/page.tsx`

### Domain workflows

Server actions and workflow logic.

- [Intake and matter actions](https://github.com/lawflow-boop/lawlink/blob/main/src/server/matters/actions.ts): server actions · Domain-facing read/write layer that converts intakes and operates matters. · `src/server/matters/actions.ts`
- [Matter lifecycle](https://github.com/lawflow-boop/lawlink/blob/main/src/server/matters/lifecycle.ts): workflow logic · Coordinates status transitions and working-record operations. · `src/server/matters/lifecycle.ts`
- [Conflict engine](https://github.com/lawflow-boop/lawlink/blob/main/src/server/conflicts/algorithm.ts): domain algorithm · Finds conflicts and supports cause recommendations. · `src/server/conflicts/algorithm.ts`
- [Finance and invoices](https://github.com/lawflow-boop/lawlink/blob/main/src/server/finance/actions.ts): server actions · Manages financial records and invoice requests independently of lifecycle actions. · `src/server/finance/actions.ts`
- **Archive workflow**: guarded workflow · Checks closure readiness and produces archival records.
- [Archive export](https://github.com/lawflow-boop/lawlink/blob/main/src/app/api/archive/%5BmatterId%5D/export/route.ts): API route · Renders an archive package for a matter. · `src/app/api/archive/[matterId]/export/route.ts`
- [Document service](https://github.com/lawflow-boop/lawlink/blob/main/src/server/documents/actions.ts): server actions · Manages matter documents and firm files. · `src/server/documents/actions.ts`
- [Scheduler and jobs](https://github.com/lawflow-boop/lawlink/blob/main/src/server/cron/scheduler.ts): automation · Runs reminder, archive, follow-up, and audit cleanup scans. · `src/server/cron/scheduler.ts`
- [Reports, imports, exports](https://github.com/lawflow-boop/lawlink/blob/main/src/server/reports/analytics.ts): operational services · Provides analytics, interchange, and XLSX exports. · `src/server/reports/analytics.ts`

### Platform and integrations

Persistence, files, external services, and deployment.

- [AI and YuanDian clients](https://github.com/lawflow-boop/lawlink/blob/main/src/lib/ai/client.ts): external integrations · Supports drafting, review, parsing, recommendations, and enterprise case services. · `src/lib/ai/client.ts`
- [File storage](https://github.com/lawflow-boop/lawlink/blob/main/src/lib/storage/provider.ts): storage abstraction · Validates and encrypts local or S3-backed files. · `src/lib/storage/provider.ts`
- [Prisma data access](https://github.com/lawflow-boop/lawlink/blob/main/src/lib/prisma.ts): database client · Application database access point for domain actions. · `src/lib/prisma.ts`
- [PostgreSQL system of record](https://github.com/lawflow-boop/lawlink/blob/main/prisma/schema.prisma): relational database · Stores firms, people, intakes, matters, documents, finance, approvals, reminders, and archives. · `prisma/schema.prisma`
- [Local and Docker deployment](https://github.com/lawflow-boop/lawlink/blob/main/docker-compose.yml): deployment · Runs the application and required local services. · `docker-compose.yml`

## Connections

- Next.js App Router → Authentication: serves
- Next.js App Router → Authenticated app shell: hosts
- Authentication → Session and permissions: creates sessions via
- Authenticated app shell → Session and permissions: requires
- Authenticated app shell → Intake and conflict UI: navigates to
- Authenticated app shell → Matter workbench: navigates to
- Intake and conflict UI → Intake and matter actions: submits workflow actions
- Intake and conflict UI → Conflict engine: requests conflict review
- Matter workbench → Intake and matter actions: operates matters through
- Matter workbench → Finance and invoices: manages finance through
- Matter workbench → Document service: manages files through
- Matter workbench → Archive workflow: closes through
- Intake and matter actions → Matter lifecycle: applies
- Intake and matter actions → Prisma data access: reads and writes
- Conflict engine → Prisma data access: searches records
- Finance and invoices → Prisma data access: persists records
- Archive workflow → Prisma data access: checks and records
- Archive workflow → Archive export: enables
- Document service → File storage: stores files in
- Document service → Prisma data access: records metadata in
- Scheduler and jobs → Prisma data access: scans operational records
- Reports, imports, exports → Prisma data access: queries operational data
- AI and YuanDian clients → Document service: drafts and reviews documents
- Prisma data access → PostgreSQL system of record: connects to
- Local and Docker deployment → Next.js App Router: runs
- Local and Docker deployment → Scheduler and jobs: must execute