# micropyramid/opensource-startup-crm architecture

> Architecture diagram of the GitHub repository micropyramid/opensource-startup-crm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/micropyramid/opensource-startup-crm
- Repository: https://github.com/micropyramid/opensource-startup-crm

## Overview

1. **Repository shape**
   - This is a single full-stack Node/SvelteKit application with a separate `api/` server layer, a Prisma/PostgreSQL data layer, and multiple route groups for different user surfaces.
   - The app is not “just a UI”; it combines server-rendered pages, form actions, authenticated CRUD screens, and REST-style backend routes.

2. **Primary runtime and framework boundary**
   - The frontend and most server-side page logic live in **SvelteKit** under `src/routes`.
   - `+page.server.js` files are the main data/mutation boundary for the UI: they load records, enforce access, and handle create/update/delete actions before rendering Svelte components.

3. **Data persistence**
   - The canonical database layer is **Prisma** in `prisma/schema.prisma` plus migrations under `prisma/migrations`.
   - `src/lib/prisma.js` is the shared Prisma client used across the app, so the architecture is centered around a single relational datastore, most likely PostgreSQL as described in the README.

4. **Multi-tenant core**
   - The product is built around **organization-scoped data isolation**. Most business records are expected to be filtered by organization membership.
   - Authentication and tenant context are enforced centrally via `src/hooks.server.js` and also in `api/middleware/auth.js`, so the tenant boundary is a first-class architectural concern, not just a UI convention.

5. **Main application surface**
   - The `(app)` route group is the authenticated CRM workspace.
   - It contains CRUD and detail/edit flows for **accounts, contacts, leads, opportunities, tasks, cases, users, profile**, and **invoices**.
   - There are specialized task views (`calendar`, `list`) and opportunity lifecycle actions like `close` and `delete`, which suggests the app is workflow-oriented rather than a generic data table UI.

6. **Public site surface**
   - The `(site)` route group is the unauthenticated marketing/public site.
   - It includes landing pages, feature pages, pricing, FAQ, privacy/terms, blog listing and blog detail pages, contact, unsubscribe, and sitemap generation.
   - This surface likely shares some content/data sources with the admin area, but it is isolated from the main CRM workspace.

7. **Authentication and unauthenticated flows**
   - The `(no-layout)` group holds login/logout and organization onboarding/selection pages, separated from both the marketing shell and the main app shell.
   - That separation indicates distinct layout and session states: public visitor, authenticated user inside an org, and auth/bootstrap flows before entering the app.

8. **Admin and platform-management boundary**
   - The `(admin)` route group is a super-admin console.
   - It manages platform-wide content and operational data such as **blogs, contacts, and newsletter subscribers**.
   - This is a separate trust boundary from the normal CRM tenant workspace and appears to be reserved for platform operators, not regular tenant users.

9. **Backend API layer**
   - The `api/` directory looks like a dedicated Node API subsystem with its own routes, middleware, and logging/error handling.
   - Routes for `auth`, `accounts`, `contacts`, `dashboard`, `leads`, `opportunities`, `organizations`, and `tasks` suggest this layer mirrors the CRM domain and likely serves JSON endpoints or internal service calls.
   - `api/config/logger.js`, `api/middleware/requestLogger.js`, and `api/middleware/errorHandler.js` show a conventional server-side request pipeline around that API.

10. **Shared domain data and utilities**
   - `src/lib/data` contains static reference data like countries, industries, lead statuses, ratings, lead sources, account types, and ownership options. These are used to standardize forms and filters across the app.
   - `src/lib/newsletter.js` and `src/lib/utils/phone.js` are small domain helpers that support marketing/contact workflows.

11. **State and client-side auth**
   - `src/lib/stores/auth.js` indicates client-side auth/session state is exposed through a Svelte store, likely to drive nav, permissions, and user context in the UI.
   - This complements server-side enforcement rather than replacing it.

12. **Content and SEO-related outputs**
   - `src/routes/sitemap.xml/+server.js` generates an XML sitemap, and the blog routes plus admin blog editor imply the public site is content-managed from the same system.
   - `static/funding.json` and public-facing content pages suggest some marketing assets are served as static data alongside rendered pages.

13. **Deployment and operational setup**
   - The repo is container-ready with a `Dockerfile`, and CI/CD is configured through GitHub Actions in `.github/workflows/build-deploy.yml`.
   - Environment-driven configuration is expected via `.env` / `.env.example`, including database connectivity and JWT/OAuth-related secrets.

14. **Diagramming summary**
   - The cleanest architecture diagram is: **browser users** split into public site, auth/bootstrap, tenant CRM app, and super-admin console; all of them talk to **SvelteKit server routes / API routes**; those routes enforce auth and tenant scope; data is persisted through **Prisma** into **PostgreSQL**.
   - The main system boundary to emphasize is the separation between **public content**, **tenant-isolated CRM operations**, and **platform admin operations**.

Main entry points: [`src/routes`](https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes) (Page actions), [`src/routes/(site)`](https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes/(site)) (Public site), [`src/routes/(admin)`](https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes/(admin)) (Admin console), [`api/routes`](https://github.com/micropyramid/opensource-startup-crm/tree/master/api/routes) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_surfaces["User surfaces"]
  node_browser(("Users<br/>clients"))
  node_site["Public site<br/>SvelteKit marketing"]
  node_bootstrap["Auth bootstrap<br/>SvelteKit auth flow"]
  node_crm["CRM workspace<br/>SvelteKit tenant app"]
  node_admin["Admin console<br/>SvelteKit super-admin"]
end

subgraph group_group_backend["Backend layers"]
  node_hooks["Server hooks<br/>SvelteKit guard<br/>[hooks.server.js]"]
  node_page_actions["Page actions<br/>SvelteKit server pages"]
  node_api_server["API server<br/>Node API"]
  node_api_mw["API middleware<br/>request pipeline"]
  node_api_routes["API routes<br/>domain endpoints"]
  node_prisma_client["Prisma client<br/>data access<br/>[prisma.js]"]
  node_schema[("Schema & migrations<br/>Prisma model<br/>[schema.prisma]")]
  node_database[("PostgreSQL<br/>relational datastore")]
end

subgraph group_group_data["Domain data"]
  node_reference_data["Reference data<br/>domain constants"]
  node_helpers["Domain helpers<br/>utility modules"]
  node_content["Content & SEO<br/>public content<br/>[sitemap.xml]"]
end

node_browser -->|"browse"| node_site
node_browser -->|"sign in"| node_bootstrap
node_browser -->|"work"| node_crm
node_browser -->|"operate"| node_admin
node_site -->|"loads"| node_page_actions
node_bootstrap -->|"actions"| node_page_actions
node_crm -->|"CRUD"| node_page_actions
node_admin -->|"manage"| node_page_actions
node_page_actions -->|"guarded by"| node_hooks
node_hooks -->|"uses"| node_prisma_client
node_page_actions -.->|"mirrors"| node_api_routes
node_api_server -->|"wraps"| node_api_mw
node_api_mw -->|"protects"| node_api_routes
node_api_routes -->|"queries"| node_prisma_client
node_prisma_client -->|"maps"| node_schema
node_schema -->|"persists to"| node_database
node_reference_data -->|"feeds forms"| node_page_actions
node_helpers -->|"supports"| node_page_actions
node_content -->|"powers"| node_site
node_content -.->|"edits"| node_admin

click node_site "https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes/(site)"
click node_bootstrap "https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes/(no-layout)"
click node_crm "https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes/(app)"
click node_admin "https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes/(admin)"
click node_hooks "https://github.com/micropyramid/opensource-startup-crm/blob/master/src/hooks.server.js"
click node_page_actions "https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes"
click node_api_server "https://github.com/micropyramid/opensource-startup-crm/tree/master/api"
click node_api_mw "https://github.com/micropyramid/opensource-startup-crm/tree/master/api/middleware"
click node_api_routes "https://github.com/micropyramid/opensource-startup-crm/tree/master/api/routes"
click node_prisma_client "https://github.com/micropyramid/opensource-startup-crm/blob/master/src/lib/prisma.js"
click node_schema "https://github.com/micropyramid/opensource-startup-crm/blob/master/prisma/schema.prisma"
click node_reference_data "https://github.com/micropyramid/opensource-startup-crm/tree/master/src/lib/data"
click node_helpers "https://github.com/micropyramid/opensource-startup-crm/tree/master/src/lib"
click node_content "https://github.com/micropyramid/opensource-startup-crm/blob/master/src/routes/sitemap.xml"

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_browser,node_site,node_bootstrap,node_crm,node_admin toneBlue
class node_hooks,node_page_actions,node_api_server,node_api_mw,node_api_routes,node_prisma_client,node_schema,node_database toneAmber
class node_reference_data,node_helpers,node_content toneMint
```

## Components

### User surfaces

Public site, auth/bootstrap, tenant app, and admin console

- **Users**: clients · Public visitors, authenticated CRM users, and admins
- [Public site](https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes/(site)): SvelteKit marketing · Landing pages, feature pages, blog, pricing, contact, and policy pages · `src/routes/(site)`
- [Auth bootstrap](https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes/(no-layout)): SvelteKit auth flow · Login, logout, org selection, and org onboarding before entering the app · `src/routes/(no-layout)`
- [CRM workspace](https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes/(app)): SvelteKit tenant app · Authenticated organization-scoped workspace for sales and service workflows · `src/routes/(app)`
- [Admin console](https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes/(admin)): SvelteKit super-admin · Platform operator area for blogs, contacts, and newsletter management · `src/routes/(admin)`

### Backend layers

SvelteKit server logic, API routes, and shared persistence

- [Server hooks](https://github.com/micropyramid/opensource-startup-crm/blob/master/src/hooks.server.js): SvelteKit guard · Central auth and tenant context enforcement for page requests · `src/hooks.server.js`
- [Page actions](https://github.com/micropyramid/opensource-startup-crm/tree/master/src/routes): SvelteKit server pages · +page.server.js boundaries that load data and handle mutations · `src/routes`
- [API server](https://github.com/micropyramid/opensource-startup-crm/tree/master/api): Node API · Separate server layer exposing domain routes and middleware · `api`
- [API middleware](https://github.com/micropyramid/opensource-startup-crm/tree/master/api/middleware): request pipeline · Auth, request logging, and error handling around API requests · `api/middleware`
- [API routes](https://github.com/micropyramid/opensource-startup-crm/tree/master/api/routes): domain endpoints · Accounts, auth, contacts, dashboard, leads, opportunities, organizations, and tasks · `api/routes`
- [Prisma client](https://github.com/micropyramid/opensource-startup-crm/blob/master/src/lib/prisma.js): data access · Shared Prisma client used across SvelteKit and API code · `src/lib/prisma.js`
- [Schema & migrations](https://github.com/micropyramid/opensource-startup-crm/blob/master/prisma/schema.prisma): Prisma model · Canonical relational schema and migration history · `prisma/schema.prisma`
- **PostgreSQL**: relational datastore · Primary persistent store for tenant and content data

### Domain data

Shared reference data and content/SEO helpers

- [Reference data](https://github.com/micropyramid/opensource-startup-crm/tree/master/src/lib/data): domain constants · Countries, industries, statuses, ratings, sources, account types, and ownership options · `src/lib/data`
- [Domain helpers](https://github.com/micropyramid/opensource-startup-crm/tree/master/src/lib): utility modules · Newsletter and phone helpers plus client-side auth state · `src/lib`
- [Content & SEO](https://github.com/micropyramid/opensource-startup-crm/blob/master/src/routes/sitemap.xml): public content · Blog, sitemap, static funding data, and marketing content · `src/routes/sitemap.xml`

## Connections

- Users → Public site: browse · Public visitors access marketing and content pages
- Users → Auth bootstrap: sign in · Users authenticate and choose or create an organization
- Users → CRM workspace: work · Authenticated tenant users use the CRM workspace
- Users → Admin console: operate · Super-admins manage platform content and subscribers
- Public site → Page actions: loads · Site pages use server-side loaders for content and forms
- Auth bootstrap → Page actions: actions · Login, logout, and org flows are handled by page server code
- CRM workspace → Page actions: CRUD · Workspace screens use server actions for records and workflow steps
- Admin console → Page actions: manage · Admin screens use server actions for editorial and subscriber operations
- Page actions → Server hooks: guarded by · Server-side page logic relies on centralized auth and tenant context
- Server hooks → Prisma client: uses · Request-scoped code reads and mutates data through Prisma
- Page actions → API routes: mirrors · App domains are also exposed through the API layer
- API server → API middleware: wraps · The API applies logging, auth, and error handling middleware
- API middleware → API routes: protects · Middleware secures and routes API requests
- API routes → Prisma client: queries · API endpoints access shared persistence through Prisma
- Prisma client → Schema & migrations: maps · The client is generated from the Prisma schema
- Schema & migrations → PostgreSQL: persists to · Migrations define the relational database structure
- Reference data → Page actions: feeds forms · Standardized options are used in CRM forms and filters
- Domain helpers → Page actions: supports · Shared helpers back newsletter, phone, and auth-related flows
- Content & SEO → Public site: powers · Marketing pages, blog routes, sitemap, and static assets form the public content layer
- Content & SEO → Admin console: edits · Admin blog management updates public-facing content
