# lin0et/dev-projects architecture

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

- Interactive diagram: https://gitdiagram.com/lin0et/dev-projects
- Repository: https://github.com/lin0et/dev-projects

## Overview

1. This is a pnpm/Nx monorepo with three main runtime surfaces: the API backend, several frontend apps, and a shared client-libraries package. The rest of the repo is supporting infrastructure: tests, scripts, config, and CI.

2. The backend lives in `api/` and is the central orchestration layer. It is a Node.js service built on Fastify, with MongoDB as the primary database. `api/src/index.js` boots loaders that wire up Fastify, Mongo, rate limiting, and Inngest.

3. Request handling on the API follows a clear layering: routers expose endpoints, controllers handle HTTP-level coordination, services contain business logic, repositories encapsulate database access, models define Mongo data shapes, and schemas/validators guard request and response contracts. This is the core boundary to diagram for the backend.

4. The backend also owns background and event-driven workflows through `api/src/functions/` and the Inngest loader. These jobs cover recurring automation such as SMS drips, rebill handling, order follow-up, shipping updates, and sync tasks, so not all domain work happens through synchronous HTTP requests.

5. External integrations are a major architectural concern in the API. Dedicated adapters under `api/src/lib/` and corresponding services wrap third parties such as Konnektive, GogoMeds, MD Integrations, Twilio, Zendesk, AfterShip, Braze, SendGrid, Slack, AWS S3, SmartyStreets, Google Maps/Auth, Facebook, and Genderize. These integrations are isolated behind service boundaries rather than called directly from controllers.

6. Authentication, authorization, and anti-abuse are enforced in middleware and loaders. The API has auth middleware, dashboard whitelisting, SSL/rate-limiting support, and webhook-specific authentication for external callbacks. Error handling is centralized in Fastify middleware, with structured logging and Sentry/Rollbar-style error reporting noted in the README.

7. MongoDB is more than a persistence layer: there are schema/index definitions, migrations, and operational scripts. The repo includes historical migrations, a migration runner config, and helper scripts for seeding, housekeeping, reporting, and data repair, which implies ongoing schema evolution and operational maintenance.

8. The frontend is split by audience and deployment. `frontend/employee` is the internal/admin/customer-service dashboard, while `frontend/patient` and the brand-specific patient apps (`patient-scoreblue`, `patient-allamericanpharma`, `patient-duckymd`, `patient-scorerx`) serve customer onboarding and account experiences. These are separate build targets rather than a single SPA.

9. The patient experience is workflow-driven. The README explicitly calls out `PatientRouter`-style logic that routes users based on onboarding progress, and the patient app contains distinct pages for survey, checkout, treatment selection, identity verification, billing, shipping, subscriptions, order history, and Zendesk redirection. That workflow is the key client-side state machine.

10. `frontend/client-libs` is the shared UI/domain package used across the frontends. It provides API client wrappers, shared constants, context providers, forms, models, reusable UI components, routing/auth helpers, and a standalone logger implementation. This is the main reuse boundary between the patient and employee apps.

11. The employee app is optimized for operational tasks and back-office tooling. Its pages focus on user lookup, employee management, order management, user detail views, CS notes, SMS blasts, queue reports, and agent checkout/demographic/survey flows. It consumes the same API and shared client-libs but presents a different operational surface.

12. End-to-end verification is a separate subsystem under `e2e-tests/`, built with Playwright. It includes environment setup, reusable page objects, fixtures, and flows for guest, customer, and agent scenarios, plus webhook and test-data utilities. This acts as the integration boundary across frontend, API, and external mocks.

13. There is also a small `scripts/` workspace for build-time utilities, such as injecting client versions and generating lockfile metadata. These are supporting tools rather than runtime services, but they matter for deployment and release consistency.

14. Local development and deployment are shaped by repo-level infrastructure: Docker Compose, Nginx config templates, a Procfile, GitHub Actions workflows for each app, and shared lint/prettier/tooling packages. This suggests a multi-app release pipeline with shared standards and independently built artifacts.

Main entry points: [`.github/workflows/patient.yml`](https://github.com/lin0et/dev-projects/blob/main/.github/workflows/patient.yml) (CI workflows), [`api/src/routers/auth.js`](https://github.com/lin0et/dev-projects/blob/main/api/src/routers/auth.js) (HTTP layer), [`api/src/index.js`](https://github.com/lin0et/dev-projects/blob/main/api/src/index.js) (Bootstrap), [`e2e-tests/playwright.config.js`](https://github.com/lin0et/dev-projects/blob/main/e2e-tests/playwright.config.js) (Playwright suite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_api["API"]
  node_api_boot["Bootstrap<br/>entry/loaders<br/>[index.js]"]
  node_api_http["HTTP layer<br/>routes/controllers<br/>[auth.js]"]
  node_api_logic["Business logic<br/>services/repositories<br/>[order.js]"]
  node_api_data[("Mongo layer<br/>models/migrations<br/>[user.model.js]")]
  node_api_integrations["Integrations<br/>adapters/lib<br/>[Konnektive.js]"]
  node_api_async["Jobs<br/>inngest/functions<br/>[index.js]"]
  node_api_security{{"Security<br/>middleware<br/>[auth.js]"}}
  node_api_logging["Logging<br/>utils/logger<br/>[index.js]"]
end

subgraph group_group_frontend["Frontends"]
  node_fe_employee["Employee app<br/>admin dashboard<br/>[App.jsx]"]
  node_fe_patient["Patient app<br/>customer workflow<br/>[App.jsx]"]
  node_fe_brand_apps["Brand apps<br/>patient shells<br/>[index.tsx]"]
  node_fe_clientlibs["Client libs<br/>shared package<br/>[auth.js]"]
  node_fe_patient_flow["Patient flow<br/>routing/pages<br/>[PatientRoute.jsx]"]
  node_fe_employee_ops["Ops pages<br/>pages/tools<br/>[index.jsx]"]
end

subgraph group_group_e2e["E2E"]
  node_e2e_suite["Playwright suite<br/>integration tests"]
  node_e2e_flows["Journey flows<br/>test flows<br/>[guest-checkout.js]"]
end

subgraph group_group_infra["Infra"]
  node_ci_workflows["CI workflows<br/>github actions<br/>[patient.yml]"]
  node_repo_tooling["Tooling<br/>shared config<br/>[base.js]"]
  node_local_deploy["Deploy setup<br/>runtime config"]
  node_scripts_ws["Scripts<br/>build utilities"]
end

node_api_boot -->|"bootstraps"| node_api_http
node_api_boot -->|"connects"| node_api_data
node_api_boot -->|"registers"| node_api_async
node_api_http -->|"protected by"| node_api_security
node_api_http -->|"delegates to"| node_api_logic
node_api_logic -->|"reads/writes"| node_api_data
node_api_logic -->|"calls"| node_api_integrations
node_api_async -->|"reuses"| node_api_logic
node_api_async -->|"syncs with"| node_api_integrations
node_api_logging -.->|"captures"| node_api_http
node_fe_patient -->|"orchestrates"| node_fe_patient_flow
node_fe_patient_flow -->|"uses"| node_fe_clientlibs
node_fe_employee -->|"hosts"| node_fe_employee_ops
node_fe_employee -->|"uses"| node_fe_clientlibs
node_fe_brand_apps -.->|"variant of"| node_fe_patient
node_fe_clientlibs -->|"calls"| node_api_http
node_e2e_suite -->|"verifies"| node_fe_patient
node_e2e_suite -->|"verifies"| node_fe_employee
node_e2e_suite -->|"hits"| node_api_http
node_e2e_flows -->|"implements"| node_e2e_suite
node_ci_workflows -->|"builds/tests"| node_api_boot
node_ci_workflows -->|"builds/tests"| node_fe_employee
node_ci_workflows -->|"builds/tests"| node_fe_patient
node_ci_workflows -->|"builds/tests"| node_fe_brand_apps
node_ci_workflows -->|"runs"| node_e2e_suite
node_repo_tooling -.->|"standardizes"| node_api_boot
node_repo_tooling -.->|"standardizes"| node_fe_clientlibs
node_repo_tooling -.->|"standardizes"| node_fe_employee
node_repo_tooling -.->|"standardizes"| node_fe_patient
node_local_deploy -.->|"supports"| node_ci_workflows
node_scripts_ws -.->|"supports release"| node_fe_clientlibs

click node_api_boot "https://github.com/lin0et/dev-projects/blob/main/api/src/index.js"
click node_api_http "https://github.com/lin0et/dev-projects/blob/main/api/src/routers/auth.js"
click node_api_logic "https://github.com/lin0et/dev-projects/blob/main/api/src/services/order.js"
click node_api_data "https://github.com/lin0et/dev-projects/blob/main/api/src/models/user.model.js"
click node_api_integrations "https://github.com/lin0et/dev-projects/blob/main/api/src/lib/Konnektive.js"
click node_api_async "https://github.com/lin0et/dev-projects/blob/main/api/src/functions/index.js"
click node_api_security "https://github.com/lin0et/dev-projects/blob/main/api/src/middleware/auth.js"
click node_api_logging "https://github.com/lin0et/dev-projects/blob/main/api/src/utils/logger/index.js"
click node_fe_employee "https://github.com/lin0et/dev-projects/blob/main/frontend/employee/src/App/App.jsx"
click node_fe_patient "https://github.com/lin0et/dev-projects/blob/main/frontend/patient/src/App/App.jsx"
click node_fe_brand_apps "https://github.com/lin0et/dev-projects/blob/main/frontend/patient-scoreblue/src/index.tsx"
click node_fe_clientlibs "https://github.com/lin0et/dev-projects/blob/main/frontend/client-libs/src/api/auth/auth.js"
click node_fe_patient_flow "https://github.com/lin0et/dev-projects/blob/main/frontend/patient/src/routes/PatientRoute.jsx"
click node_fe_employee_ops "https://github.com/lin0et/dev-projects/blob/main/frontend/employee/src/pages/AdminUserDetailPage/index.jsx"
click node_e2e_suite "https://github.com/lin0et/dev-projects/blob/main/e2e-tests/playwright.config.js"
click node_e2e_flows "https://github.com/lin0et/dev-projects/blob/main/e2e-tests/tests/flows/guest-checkout.js"
click node_ci_workflows "https://github.com/lin0et/dev-projects/blob/main/.github/workflows/patient.yml"
click node_repo_tooling "https://github.com/lin0et/dev-projects/blob/main/modules/tooling/src/eslint/configs/base.js"
click node_local_deploy "https://github.com/lin0et/dev-projects/blob/main/compose-local-dev.yaml"
click node_scripts_ws "https://github.com/lin0et/dev-projects/blob/main/scripts/src/apps/inject-client-version/inject-client-version.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_api_boot,node_api_http,node_api_logic,node_api_data,node_api_integrations,node_api_async,node_api_security,node_api_logging toneBlue
class node_fe_employee,node_fe_patient,node_fe_brand_apps,node_fe_clientlibs,node_fe_patient_flow,node_fe_employee_ops toneAmber
class node_e2e_suite,node_e2e_flows toneMint
class node_ci_workflows,node_repo_tooling,node_local_deploy,node_scripts_ws toneRose
```

## Components

### API

Node.js backend, domain services, persistence, and async workflows.

- [Bootstrap](https://github.com/lin0et/dev-projects/blob/main/api/src/index.js): entry/loaders · Boot sequence that wires Fastify, MongoDB, rate limiting, and Inngest. · `api/src/index.js`
- [HTTP layer](https://github.com/lin0et/dev-projects/blob/main/api/src/routers/auth.js): routes/controllers · Fastify request boundary: routers, controllers, middleware, schemas, and validators. · `api/src/routers/auth.js`
- [Business logic](https://github.com/lin0et/dev-projects/blob/main/api/src/services/order.js): services/repositories · Domain services and repositories that coordinate core API behavior. · `api/src/services/order.js`
- [Mongo layer](https://github.com/lin0et/dev-projects/blob/main/api/src/models/user.model.js): models/migrations · Mongo models, indexes, migrations, and operational data-shaping scripts. · `api/src/models/user.model.js`
- [Integrations](https://github.com/lin0et/dev-projects/blob/main/api/src/lib/Konnektive.js): adapters/lib · Third-party adapters and wrappers for messaging, pharmacy, auth, shipping, CRM, and support systems. · `api/src/lib/Konnektive.js`
- [Jobs](https://github.com/lin0et/dev-projects/blob/main/api/src/functions/index.js): inngest/functions · Background and event-driven workflows for drips, rebills, syncs, fulfillment, and follow-up. · `api/src/functions/index.js`
- [Security](https://github.com/lin0et/dev-projects/blob/main/api/src/middleware/auth.js): middleware · Authentication, dashboard whitelisting, SSL, and rate limiting. · `api/src/middleware/auth.js`
- [Logging](https://github.com/lin0et/dev-projects/blob/main/api/src/utils/logger/index.js): utils/logger · Structured logging and error reporting pipeline, including Sentry-backed providers. · `api/src/utils/logger/index.js`

### Frontends

Employee and patient applications plus shared client libraries.

- [Employee app](https://github.com/lin0et/dev-projects/blob/main/frontend/employee/src/App/App.jsx): admin dashboard · Internal operational UI for customer service, orders, users, and tools. · `frontend/employee/src/App/App.jsx`
- [Patient app](https://github.com/lin0et/dev-projects/blob/main/frontend/patient/src/App/App.jsx): customer workflow · Patient-facing onboarding and account experience with routing driven by onboarding state. · `frontend/patient/src/App/App.jsx`
- [Brand apps](https://github.com/lin0et/dev-projects/blob/main/frontend/patient-scoreblue/src/index.tsx): patient shells · Brand-specific patient deployment targets for distinct customers and builds. · `frontend/patient-scoreblue/src/index.tsx`
- [Client libs](https://github.com/lin0et/dev-projects/blob/main/frontend/client-libs/src/api/auth/auth.js): shared package · Shared API clients, constants, contexts, forms, models, UI components, and helpers used by both frontends. · `frontend/client-libs/src/api/auth/auth.js`
- [Patient flow](https://github.com/lin0et/dev-projects/blob/main/frontend/patient/src/routes/PatientRoute.jsx): routing/pages · Patient workflow pages for survey, checkout, verification, billing, shipping, subscriptions, and support redirects. · `frontend/patient/src/routes/PatientRoute.jsx`
- [Ops pages](https://github.com/lin0et/dev-projects/blob/main/frontend/employee/src/pages/AdminUserDetailPage/index.jsx): pages/tools · Operational pages for user lookup, employee management, queue reports, SMS blasts, and agent checkout flows. · `frontend/employee/src/pages/AdminUserDetailPage/index.jsx`

### E2E

Playwright integration and workflow verification.

- [Playwright suite](https://github.com/lin0et/dev-projects/blob/main/e2e-tests/playwright.config.js): integration tests · Cross-app end-to-end verification for guest, customer, and agent journeys. · `e2e-tests/playwright.config.js`
- [Journey flows](https://github.com/lin0et/dev-projects/blob/main/e2e-tests/tests/flows/guest-checkout.js): test flows · Reusable guest, customer, and webhook flows plus page objects and fixtures. · `e2e-tests/tests/flows/guest-checkout.js`

### Infra

Repo-level config, deployment, and CI support.

- [CI workflows](https://github.com/lin0et/dev-projects/blob/main/.github/workflows/patient.yml): github actions · Independent build/test workflows for the API, client libs, patient apps, employee app, and e2e runs. · `.github/workflows/patient.yml`
- [Tooling](https://github.com/lin0et/dev-projects/blob/main/modules/tooling/src/eslint/configs/base.js): shared config · Monorepo-wide lint, prettier, TypeScript, Nx, and release/development helpers. · `modules/tooling/src/eslint/configs/base.js`
- [Deploy setup](https://github.com/lin0et/dev-projects/blob/main/compose-local-dev.yaml): runtime config · Local and production-supporting configuration such as Docker Compose, Nginx templates, Procfile, and workspace settings. · `compose-local-dev.yaml`
- [Scripts](https://github.com/lin0et/dev-projects/blob/main/scripts/src/apps/inject-client-version/inject-client-version.ts): build utilities · Small workspace for build-time utilities like client version injection and lockfile metadata generation. · `scripts/src/apps/inject-client-version/inject-client-version.ts`

## Connections

- Bootstrap → HTTP layer: bootstraps · Entry point loads the request stack and shared loaders.
- Bootstrap → Mongo layer: connects · Startup initializes persistence and schema-related wiring.
- Bootstrap → Jobs: registers · Boot sequence wires Inngest handlers and background jobs.
- HTTP layer → Security: protected by · Request handlers are guarded by auth, whitelisting, SSL, and rate limiting.
- HTTP layer → Business logic: delegates to · Controllers and routers pass domain work into services and repositories.
- Business logic → Mongo layer: reads/writes · Business logic persists through Mongo models and repositories.
- Business logic → Integrations: calls · Domain services isolate third-party interactions behind adapters.
- Jobs → Business logic: reuses · Background jobs share the same business logic boundary as HTTP flows.
- Jobs → Integrations: syncs with · Jobs drive messaging, fulfillment, CRM, and pharmacy integrations.
- Logging → HTTP layer: captures · Centralized logging and error reporting wraps the Fastify surface.
- Patient app → Patient flow: orchestrates · Patient app is structured around onboarding-state routing and stepwise pages.
- Patient flow → Client libs: uses · Patient workflow pages rely on shared forms, models, and helpers.
- Employee app → Ops pages: hosts · Employee app exposes the back-office operational page set.
- Employee app → Client libs: uses · Operational screens share API clients, contexts, and UI primitives.
- Brand apps → Patient app: variant of · Brand-specific patient shells follow the same patient experience architecture.
- Client libs → HTTP layer: calls · Shared API wrappers encode the backend contract for frontends.
- Playwright suite → Patient app: verifies · Playwright covers guest and customer journeys through the patient app.
- Playwright suite → Employee app: verifies · Playwright covers agent and admin scenarios through the employee app.
- Playwright suite → HTTP layer: hits · End-to-end tests exercise backend endpoints and webhooks.
- Journey flows → Playwright suite: implements · Flows, fixtures, and page objects provide reusable test orchestration.
- CI workflows → Bootstrap: builds/tests · CI runs backend build and verification jobs.
- CI workflows → Employee app: builds/tests · CI runs employee app pipelines.
- CI workflows → Patient app: builds/tests · CI runs patient app pipelines.
- CI workflows → Brand apps: builds/tests · CI runs brand-specific patient app pipelines.
- CI workflows → Playwright suite: runs · Dedicated workflows execute Playwright integration suites.
- Tooling → Bootstrap: standardizes · Shared tooling constrains backend linting, formatting, and TypeScript settings.
- Tooling → Client libs: standardizes · Shared tooling constrains the client-libs package.
- Tooling → Employee app: standardizes · Shared tooling constrains the employee app.
- Tooling → Patient app: standardizes · Shared tooling constrains the patient app.
- Deploy setup → CI workflows: supports · Repo-level runtime and deployment config underpins CI and local execution.
- Scripts → Client libs: supports release · Build-time utilities help inject versions and maintain lockfile metadata.