# mrmls-dev/nhs-mono-app architecture

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

- Interactive diagram: https://gitdiagram.com/mrmls-dev/nhs-mono-app
- Repository: https://github.com/mrmls-dev/nhs-mono-app

## Overview

1. This repository is a monorepo with two runtime apps and shared packages: a Next.js frontend in `apps/web`, a NestJS backend API in `apps/api`, and reusable UI/tooling in `packages/*`. The overall product appears to be a multi-tenant real-estate/agent marketing platform, based on the domain models and routes for agents, communities, counties, regions, floor plans, contacts, and branding.

2. The frontend (`apps/web`) is the user-facing application. It uses the Next.js App Router and is split into three major route groups: public marketing pages, authentication pages, and a protected dashboard. This separation is important for diagramming because each group has a different rendering and authorization boundary.

3. Public marketing pages render community and plan detail pages, schedule pages, and Open Graph image endpoints. These pages also rely on a mix of static assets in `apps/web/public` and local data files in `apps/web/data`, which suggests some public content is prebuilt or semi-static rather than always fetched from the API.

4. The dashboard area is the main authenticated workspace. It contains management screens for agents, communities, counties, regions, contacts, listings, members, integrations, SEO, domains, branding, and scheduling embeds. Many of these screens are composed from client-side components under `app/dashboard/**/_components`, indicating that the dashboard is interactive and form-heavy while still leveraging server-side route structure.

5. The web app’s data access is centralized in `apps/web/lib/api/*`, with one client module per backend domain area. This is the main frontend-to-backend boundary: UI components talk to these API wrappers, which in turn call the NestJS service. `apps/web/lib/auth-client.ts` and `apps/web/proxy.ts` indicate auth/session handling is wired into the frontend request path, likely to protect dashboard routes and attach session context.

6. The backend (`apps/api`) is a modular NestJS service. Each business area is isolated into its own module, controller, and service: agents, communities, counties, floor plans, regions, staff, marketing contacts, integrations, stats, storage, Mapbox token management, GHL, Vercel, and auth. For an architecture diagram, these modules are the core domain boxes behind a single API boundary.

7. Persistence is handled through Prisma in `apps/api/prisma`, with generated client code, migrations, and a seed script. The schema includes both business entities and auth/tenant entities such as Organization, Member, User, Session, Account, Invitation, and Verification, plus domain entities like Community, County, Region, FloorPlanModel, MarketingContact, and integration records. This implies the database is the system of record for both tenant identity and marketing content.

8. Authentication and authorization are first-class backend concerns. The API has dedicated auth modules, guards, decorators, and role/session support, which means request processing likely flows through session validation and role checks before domain services run. The presence of organization/member tables suggests access control is tenant-scoped rather than purely user-scoped.

9. Several backend modules represent external integrations or platform concerns rather than core CRUD. `ghl` and `integrations` point to GoHighLevel-style marketing automation integration, `vercel` likely manages deployment or environment linkage, `mapbox` handles token provisioning, and `storage` suggests file/media handling. These should be drawn as outbound integration points from the API, not from the frontend.

10. Shared packages separate cross-cutting concerns from app logic. `packages/ui` contains the design system and shadcn-style components consumed by the web app, while `packages/typescript-config` and `packages/eslint-config` standardize build and code-quality settings across the repo. This keeps UI primitives and tooling boundaries distinct from the business applications.

11. The monorepo is managed with Turbo and package-lock-based workspace tooling, so build/test boundaries are likely optimized around app/package dependency graphs. In practical terms, the architecture is not just “frontend talks to backend”; it is “Next.js app + Nest API + shared UI packages + centralized DB,” with each domain isolated into modules on the backend and route groups on the frontend.

Main entry points: [`apps/api/src/app.module.ts`](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/app.module.ts) (API app), [`apps/web/app/layout.tsx`](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/app/layout.tsx) (Next app), [`turbo.json`](https://github.com/mrmls-dev/nhs-mono-app/blob/main/turbo.json) (Workspace), [`apps/web/app/dashboard/page.tsx`](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/app/dashboard/page.tsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
  node_workspace["Workspace<br/>turborepo monorepo<br/>[turbo.json]"]
end

subgraph group_web["Web app"]
  node_web_app["Next app<br/>Next.js frontend<br/>[layout.tsx]"]
  node_web_marketing["Marketing<br/>public routes<br/>[page.tsx]"]
  node_web_auth["Auth area<br/>login routes<br/>[page.tsx]"]
  node_web_dashboard["Dashboard<br/>protected workspace<br/>[page.tsx]"]
  node_web_components["Shared UI<br/>frontend components"]
  node_web_api_client["API client<br/>frontend data access<br/>[agent.ts]"]
  node_web_auth_client["Session client<br/>auth/session wiring<br/>[auth-client.ts]"]
  node_web_proxy["Route proxy<br/>request middleware<br/>[proxy.ts]"]
end

subgraph group_api["API app"]
  node_api_app["API app<br/>NestJS backend<br/>[app.module.ts]"]
  node_api_auth["Auth module<br/>session and roles<br/>[auth.module.ts]"]
  node_api_agents["Agents<br/>domain module<br/>[agent.module.ts]"]
  node_api_communities["Communities<br/>domain module"]
  node_api_geo["Geography<br/>domain modules<br/>[county.module.ts]"]
  node_api_content["Floor plans<br/>domain module"]
  node_api_contacts["Contacts<br/>domain module"]
  node_api_integrations["Integrations<br/>platform modules"]
  node_api_prisma[("Prisma DB<br/>persistence layer<br/>[schema.prisma]")]
end

subgraph group_shared["Shared packages"]
  node_ui_pkg["UI package<br/>shared design system<br/>[button.tsx]"]
  node_ts_pkg["TS config<br/>shared tooling<br/>[base.json]"]
  node_eslint_pkg["Lint config<br/>shared tooling<br/>[base.js]"]
end

node_workspace -->|"manages"| node_web_app
node_workspace -->|"manages"| node_api_app
node_workspace -->|"shares"| node_ui_pkg
node_workspace -->|"shares"| node_ts_pkg
node_workspace -->|"shares"| node_eslint_pkg
node_web_app -->|"routes"| node_web_marketing
node_web_app -->|"routes"| node_web_auth
node_web_app -->|"routes"| node_web_dashboard
node_web_dashboard -->|"composes"| node_web_components
node_web_marketing -->|"reads"| node_web_api_client
node_web_dashboard -->|"reads"| node_web_api_client
node_web_dashboard -->|"guards"| node_web_auth_client
node_web_proxy -->|"protects"| node_web_dashboard
node_web_app -->|"uses"| node_ui_pkg
node_web_app -->|"calls"| node_api_app
node_api_app -->|"uses"| node_api_auth
node_api_app -->|"hosts"| node_api_agents
node_api_app -->|"hosts"| node_api_communities
node_api_app -->|"hosts"| node_api_geo
node_api_app -->|"hosts"| node_api_content
node_api_app -->|"hosts"| node_api_contacts
node_api_app -->|"hosts"| node_api_integrations
node_api_app -->|"persists"| node_api_prisma
node_api_integrations -->|"stores"| node_api_prisma
node_web_api_client -->|"fetches"| node_api_app
node_web_auth_client -->|"sessions"| node_api_auth

click node_workspace "https://github.com/mrmls-dev/nhs-mono-app/blob/main/turbo.json"
click node_web_app "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/app/layout.tsx"
click node_web_marketing "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/app/(marketing)/page.tsx"
click node_web_auth "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/app/(auth)/login/page.tsx"
click node_web_dashboard "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/app/dashboard/page.tsx"
click node_web_components "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/components/BrandThemeProvider.tsx"
click node_web_api_client "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/lib/api/agent.ts"
click node_web_auth_client "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/lib/auth-client.ts"
click node_web_proxy "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/proxy.ts"
click node_api_app "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/app.module.ts"
click node_api_auth "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/auth/auth.module.ts"
click node_api_agents "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/agent/agent.module.ts"
click node_api_communities "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/community/community.module.ts"
click node_api_geo "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/county/county.module.ts"
click node_api_content "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/floor-plan/floor-plan.module.ts"
click node_api_contacts "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/marketing-contacts/marketing-contacts.module.ts"
click node_api_integrations "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/integrations/integrations.module.ts"
click node_api_prisma "https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/prisma/schema.prisma"
click node_ui_pkg "https://github.com/mrmls-dev/nhs-mono-app/blob/main/packages/ui/src/components/button.tsx"
click node_ts_pkg "https://github.com/mrmls-dev/nhs-mono-app/blob/main/packages/typescript-config/base.json"
click node_eslint_pkg "https://github.com/mrmls-dev/nhs-mono-app/blob/main/packages/eslint-config/base.js"

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_workspace toneBlue
class node_web_app,node_web_marketing,node_web_auth,node_web_dashboard,node_web_components,node_web_api_client,node_web_auth_client,node_web_proxy toneAmber
class node_api_app,node_api_auth,node_api_agents,node_api_communities,node_api_geo,node_api_content,node_api_contacts,node_api_integrations,node_api_prisma toneMint
class node_ui_pkg,node_ts_pkg,node_eslint_pkg toneRose
```

## Components

### Monorepo

Workspace for frontend, backend, and shared packages.

- [Workspace](https://github.com/mrmls-dev/nhs-mono-app/blob/main/turbo.json): turborepo monorepo · Top-level repo orchestration and shared workspace tooling. · `turbo.json`

### Web app

Next.js frontend with marketing, auth, and dashboard route boundaries.

- [Next app](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/app/layout.tsx): Next.js frontend · User-facing application built with the App Router. · `apps/web/app/layout.tsx`
- [Marketing](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/app/(marketing)/page.tsx): public routes · Public community, plan, schedule, and Open Graph pages. · `apps/web/app/(marketing)/page.tsx`
- [Auth area](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/app/(auth)/login/page.tsx): login routes · Authentication boundary for sign-in pages and layout. · `apps/web/app/(auth)/login/page.tsx`
- [Dashboard](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/app/dashboard/page.tsx): protected workspace · Authenticated admin area for managing tenants and marketing content. · `apps/web/app/dashboard/page.tsx`
- [Shared UI](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/components/BrandThemeProvider.tsx): frontend components · Reusable client components and dashboard page pieces. · `apps/web/components/BrandThemeProvider.tsx`
- [API client](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/lib/api/agent.ts): frontend data access · Typed wrappers used by the web app to call backend domains. · `apps/web/lib/api/agent.ts`
- [Session client](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/lib/auth-client.ts): auth/session wiring · Frontend session and request protection helpers. · `apps/web/lib/auth-client.ts`
- [Route proxy](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/web/proxy.ts): request middleware · Protects dashboard traffic and forwards auth context. · `apps/web/proxy.ts`

### API app

NestJS backend organized by domain modules.

- [API app](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/app.module.ts): NestJS backend · Modular service boundary exposing business and integration APIs. · `apps/api/src/app.module.ts`
- [Auth module](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/auth/auth.module.ts): session and roles · Session validation, role checks, decorators, and auth flows. · `apps/api/src/auth/auth.module.ts`
- [Agents](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/agent/agent.module.ts): domain module · Agent management and branding/coverage domain logic. · `apps/api/src/agent/agent.module.ts`
- [Communities](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/community/community.module.ts): domain module · Community records and related content management. · `apps/api/src/community/community.module.ts`
- [Geography](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/county/county.module.ts): domain modules · County and region management for market structure. · `apps/api/src/county/county.module.ts`
- [Floor plans](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/floor-plan/floor-plan.module.ts): domain module · Floor plan and media management for listings content. · `apps/api/src/floor-plan/floor-plan.module.ts`
- [Contacts](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/marketing-contacts/marketing-contacts.module.ts): domain module · Marketing contact management and list operations. · `apps/api/src/marketing-contacts/marketing-contacts.module.ts`
- [Integrations](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/src/integrations/integrations.module.ts): platform modules · External platform concerns such as GHL, Vercel, storage, Mapbox, and stats. · `apps/api/src/integrations/integrations.module.ts`
- [Prisma DB](https://github.com/mrmls-dev/nhs-mono-app/blob/main/apps/api/prisma/schema.prisma): persistence layer · Database schema, generated client, migrations, and seed data. · `apps/api/prisma/schema.prisma`

### Shared packages

Reusable UI and tooling packages consumed across apps.

- [UI package](https://github.com/mrmls-dev/nhs-mono-app/blob/main/packages/ui/src/components/button.tsx): shared design system · Reusable component library consumed by the web app. · `packages/ui/src/components/button.tsx`
- [TS config](https://github.com/mrmls-dev/nhs-mono-app/blob/main/packages/typescript-config/base.json): shared tooling · Workspace TypeScript presets for apps and libraries. · `packages/typescript-config/base.json`
- [Lint config](https://github.com/mrmls-dev/nhs-mono-app/blob/main/packages/eslint-config/base.js): shared tooling · Common ESLint presets for repository-wide consistency. · `packages/eslint-config/base.js`

## Connections

- Workspace → Next app: manages · Workspace orchestrates the frontend application.
- Workspace → API app: manages · Workspace orchestrates the backend application.
- Workspace → UI package: shares · Common UI package is consumed by the frontend.
- Workspace → TS config: shares · TypeScript presets are shared across packages and apps.
- Workspace → Lint config: shares · ESLint presets are shared across packages and apps.
- Next app → Marketing: routes · Public App Router group for marketing pages.
- Next app → Auth area: routes · Authentication route group for sign-in flows.
- Next app → Dashboard: routes · Protected dashboard route group for admin workflows.
- Dashboard → Shared UI: composes · Dashboard screens are assembled from reusable client components.
- Marketing → API client: reads · Public pages can fetch domain data through frontend API wrappers.
- Dashboard → API client: reads · Dashboard forms and tables call backend through typed clients.
- Dashboard → Session client: guards · Dashboard behavior depends on session and auth helpers.
- Route proxy → Dashboard: protects · Proxy enforces authenticated access to protected routes.
- Next app → UI package: uses · Frontend renders shared UI primitives from the design system.
- Next app → API app: calls · Frontend communicates with the backend service boundary.
- API app → Auth module: uses · Backend requests flow through auth/session enforcement.
- API app → Agents: hosts · API exposes agent domain endpoints.
- API app → Communities: hosts · API exposes community domain endpoints.
- API app → Geography: hosts · API exposes county and region endpoints.
- API app → Floor plans: hosts · API exposes floor plan endpoints.
- API app → Contacts: hosts · API exposes contact endpoints.
- API app → Integrations: hosts · API exposes platform and external integration modules.
- API app → Prisma DB: persists · Backend reads and writes system-of-record data through Prisma.
- Integrations → Prisma DB: stores · Integration state is persisted in the shared database.
- API client → API app: fetches · Frontend data access wrappers call the NestJS API.
- Session client → Auth module: sessions · Frontend auth helpers align with backend session handling.