# samjoshua2002/educrm architecture

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

- Interactive diagram: https://gitdiagram.com/samjoshua2002/educrm
- Repository: https://github.com/samjoshua2002/educrm

## Overview

#### Purpose and topology
`educrm` is a multi-tenant admissions CRM split into a Next.js administrative/public portal and a NestJS tenant API. It supports superadmin organization management, organization operations, staff/admin workflows, applicant self-service, public forms, lead capture, applications, and academic master data.
- `admissions-mm-admin-main/src/app`
- `admissions-tenant-api-main/src/app.module.ts`
- `docker-compose.yml`

#### Frontend entry points and role boundaries
The Next.js App Router frontend separates experiences by route group and role: authentication, internal main/admin views, applicant views, organization tenant views, and superadmin views. Layouts and role-specific sidebars provide the principal UI shell boundary.
- `admissions-mm-admin-main/src/app/layout.tsx`
- `admissions-mm-admin-main/src/app/organization/layout.tsx`
- `admissions-mm-admin-main/src/app/superadmin/layout.tsx`

#### Public form and lead ingestion
Public form URLs resolve by slug, while the backend exposes public-form submission and form-response endpoints. Submission data is persisted as form responses/submissions and feeds lead ingestion; lead assignment, verification, notes, status changes, and closure are separate workflow concerns.
- `admissions-mm-admin-main/src/app/f/[slug]/page.tsx`
- `admissions-tenant-api-main/src/modules/forms/public-forms.controller.ts`
- `admissions-tenant-api-main/src/modules/leads/lead-ingestion.service.ts`

#### Admissions and application lifecycle
Applications are a core domain aggregate with section-specific records for addresses, education, parents, work experience, qualifications, tests, and activities. Organization and main/admin application pages consume this lifecycle; the user portal exposes “my application.” Status updates and application activities form the audit/progression path.
- `admissions-tenant-api-main/src/modules/applications/applications.service.ts`
- `admissions-tenant-api-main/src/modules/applications/entities/application.entity.ts`
- `admissions-mm-admin-main/src/app/(user)/my-application/page.tsx`

#### Tenant administration and master data
Organizations are the tenancy root. Their staff administer branches, courses, academic sessions, course sessions, users/team members, forms, leads, applications, communications, payments, events, and students through organization-scoped routes and API modules.
- `admissions-tenant-api-main/src/modules/organizations/organizations.service.ts`
- `admissions-tenant-api-main/src/modules/branches/branches.service.ts`
- `admissions-mm-admin-main/src/app/organization/settings/page.tsx`

#### Authentication, authorization, and tenancy boundary
The API uses JWT authentication plus role and tenant guards, with common response transformation and exception handling. Frontend middleware is the corresponding route-access boundary; client auth state is maintained separately. Superadmin routes manage organizations and subscriptions, distinct from tenant routes.
- `admissions-tenant-api-main/src/common/guards/jwt-auth.guard.ts`
- `admissions-tenant-api-main/src/common/guards/tenant.guard.ts`
- `admissions-mm-admin-main/src/middleware.ts`

#### Data access, API integration, and runtime infrastructure
The frontend uses an API client, domain hooks, and a React Query provider/query client to fetch and cache backend resources. The Nest API follows controller → service → entity/DTO module boundaries and is backed by the schema represented in `Database.sql`. A local Next upload route is present; no specific third-party storage, payment, or messaging provider is identifiable from the tree.
- `admissions-mm-admin-main/src/lib/api.ts`
- `admissions-mm-admin-main/src/components/providers/query-provider.tsx`
- `admissions-tenant-api-main/Database.sql`

Main entry points: [`admissions-mm-admin-main/src/app/layout.tsx`](https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/layout.tsx) (App Router shells), [`admissions-tenant-api-main/src/app.module.ts`](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/app.module.ts) (Nest application), [`admissions-mm-admin-main/src/lib/api.ts`](https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/lib/api.ts) (API client and cache), [`admissions-tenant-api-main/src/modules/organizations/organizations.service.ts`](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/organizations/organizations.service.ts) (Organizations and branches)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js portal"]
  node_app_router["App Router shells<br/>Next.js routes<br/>[layout.tsx]"]
  node_organization_ui["Organization operations<br/>tenant UI<br/>[layout.tsx]"]
  node_superadmin_ui["Superadmin console<br/>admin UI<br/>[layout.tsx]"]
  node_applicant_ui["My application<br/>applicant UI<br/>[page.tsx]"]
  node_public_form_ui["Public form by slug<br/>public UI<br/>[page.tsx]"]
  node_route_middleware{{"Route access middleware<br/>access control<br/>[middleware.ts]"}}
  node_api_client["API client and cache<br/>integration layer<br/>[api.ts]"]
  node_query_provider["React Query provider<br/>client state<br/>[query-provider.tsx]"]
end

subgraph group_api["NestJS tenant API"]
  node_nest_app["Nest application<br/>API composition<br/>[app.module.ts]"]
  node_auth_tenant_guards{{"JWT and tenant guards<br/>authorization boundary<br/>[jwt-auth.guard.ts]"}}
  node_organizations["Organizations and branches<br/>tenancy domain"]
  node_master_data["Academic master data<br/>tenant domain"]
  node_public_forms["Public forms API<br/>public endpoint"]
  node_lead_ingestion["Lead ingestion workflow<br/>lead domain"]
  node_applications["Applications lifecycle<br/>admissions domain"]
  node_application_entity["Application aggregate<br/>entity"]
end

subgraph group_data["Data and runtime"]
  node_database[("CRM database schema<br/>SQL schema<br/>[Database.sql]")]
  node_compose["Local runtime stack<br/>Docker Compose<br/>[docker-compose.yml]"]
end

node_route_middleware -->|"protects routes"| node_app_router
node_app_router -->|"hosts"| node_organization_ui
node_app_router -->|"hosts"| node_superadmin_ui
node_app_router -->|"hosts"| node_applicant_ui
node_app_router -->|"hosts"| node_public_form_ui
node_query_provider -->|"caches queries"| node_api_client
node_organization_ui -->|"uses"| node_api_client
node_superadmin_ui -->|"uses"| node_api_client
node_applicant_ui -->|"uses"| node_api_client
node_public_form_ui -->|"submits responses"| node_public_forms
node_api_client -->|"calls"| node_nest_app
node_nest_app -->|"applies"| node_auth_tenant_guards
node_auth_tenant_guards -->|"enforces tenant scope"| node_organizations
node_nest_app -->|"exposes"| node_public_forms
node_public_forms -->|"feeds submissions"| node_lead_ingestion
node_nest_app -->|"serves"| node_applications
node_applications -->|"manages"| node_application_entity
node_organizations -->|"scopes"| node_master_data
node_organizations -->|"scopes"| node_applications
node_organizations -->|"persists"| node_database
node_applications -->|"persists"| node_database
node_lead_ingestion -->|"persists"| node_database
node_compose -.->|"runs"| node_nest_app

click node_app_router "https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/layout.tsx"
click node_organization_ui "https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/organization/layout.tsx"
click node_superadmin_ui "https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/superadmin/layout.tsx"
click node_applicant_ui "https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/(user)/my-application/page.tsx"
click node_public_form_ui "https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/f/%5Bslug%5D/page.tsx"
click node_route_middleware "https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/middleware.ts"
click node_api_client "https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/lib/api.ts"
click node_query_provider "https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/components/providers/query-provider.tsx"
click node_nest_app "https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/app.module.ts"
click node_auth_tenant_guards "https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/common/guards/jwt-auth.guard.ts"
click node_organizations "https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/organizations/organizations.service.ts"
click node_master_data "https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/branches/branches.service.ts"
click node_public_forms "https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/forms/public-forms.controller.ts"
click node_lead_ingestion "https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/leads/lead-ingestion.service.ts"
click node_applications "https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/applications/applications.service.ts"
click node_application_entity "https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/applications/entities/application.entity.ts"
click node_database "https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/Database.sql"
click node_compose "https://github.com/samjoshua2002/educrm/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_app_router,node_organization_ui,node_superadmin_ui,node_applicant_ui,node_public_form_ui,node_route_middleware,node_api_client,node_query_provider toneBlue
class node_nest_app,node_auth_tenant_guards,node_organizations,node_master_data,node_public_forms,node_lead_ingestion,node_applications,node_application_entity toneAmber
class node_database,node_compose toneMint
```

## Components

### Next.js portal

Role-separated administrative, tenant, applicant, and public experiences.

- [App Router shells](https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/layout.tsx): Next.js routes · Layouts establish internal, organization, and superadmin UI boundaries. · `admissions-mm-admin-main/src/app/layout.tsx`
- [Organization operations](https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/organization/layout.tsx): tenant UI · Organization-scoped administration for settings and operational domains. · `admissions-mm-admin-main/src/app/organization/layout.tsx`
- [Superadmin console](https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/superadmin/layout.tsx): admin UI · Manages organizations and subscriptions separately from tenant routes. · `admissions-mm-admin-main/src/app/superadmin/layout.tsx`
- [My application](https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/(user)/my-application/page.tsx): applicant UI · `admissions-mm-admin-main/src/app/(user)/my-application/page.tsx`
- [Public form by slug](https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/app/f/%5Bslug%5D/page.tsx): public UI · `admissions-mm-admin-main/src/app/f/[slug]/page.tsx`
- [Route access middleware](https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/middleware.ts): access control · Frontend route-access boundary. · `admissions-mm-admin-main/src/middleware.ts`
- [API client and cache](https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/lib/api.ts): integration layer · Domain hooks use the API client and React Query cache. · `admissions-mm-admin-main/src/lib/api.ts`
- [React Query provider](https://github.com/samjoshua2002/educrm/blob/main/admissions-mm-admin-main/src/components/providers/query-provider.tsx): client state · `admissions-mm-admin-main/src/components/providers/query-provider.tsx`

### NestJS tenant API

Tenant-scoped domain API and workflow layer.

- [Nest application](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/app.module.ts): API composition · Composes tenant API modules. · `admissions-tenant-api-main/src/app.module.ts`
- [JWT and tenant guards](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/common/guards/jwt-auth.guard.ts): authorization boundary · Authenticates requests and enforces role and tenant scope. · `admissions-tenant-api-main/src/common/guards/jwt-auth.guard.ts`
- [Organizations and branches](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/organizations/organizations.service.ts): tenancy domain · Organizations are the tenancy root; branches are organization-scoped. · `admissions-tenant-api-main/src/modules/organizations/organizations.service.ts`
- [Academic master data](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/branches/branches.service.ts): tenant domain · Courses, sessions, users, and related tenant administration. · `admissions-tenant-api-main/src/modules/branches/branches.service.ts`
- [Public forms API](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/forms/public-forms.controller.ts): public endpoint · Resolves forms and accepts form responses. · `admissions-tenant-api-main/src/modules/forms/public-forms.controller.ts`
- [Lead ingestion workflow](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/leads/lead-ingestion.service.ts): lead domain · Turns submissions into leads for assignment and follow-up. · `admissions-tenant-api-main/src/modules/leads/lead-ingestion.service.ts`
- [Applications lifecycle](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/applications/applications.service.ts): admissions domain · Manages applications, section records, status changes, and activities. · `admissions-tenant-api-main/src/modules/applications/applications.service.ts`
- [Application aggregate](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/src/modules/applications/entities/application.entity.ts): entity · Core application record with section-specific admissions data. · `admissions-tenant-api-main/src/modules/applications/entities/application.entity.ts`

### Data and runtime

- [CRM database schema](https://github.com/samjoshua2002/educrm/blob/main/admissions-tenant-api-main/Database.sql): SQL schema · Persistence schema for tenant and admissions domains. · `admissions-tenant-api-main/Database.sql`
- [Local runtime stack](https://github.com/samjoshua2002/educrm/blob/main/docker-compose.yml): Docker Compose · `docker-compose.yml`

## Connections

- Route access middleware → App Router shells: protects routes
- App Router shells → Organization operations: hosts
- App Router shells → Superadmin console: hosts
- App Router shells → My application: hosts
- App Router shells → Public form by slug: hosts
- React Query provider → API client and cache: caches queries
- Organization operations → API client and cache: uses
- Superadmin console → API client and cache: uses
- My application → API client and cache: uses
- Public form by slug → Public forms API: submits responses
- API client and cache → Nest application: calls
- Nest application → JWT and tenant guards: applies
- JWT and tenant guards → Organizations and branches: enforces tenant scope
- Nest application → Public forms API: exposes
- Public forms API → Lead ingestion workflow: feeds submissions
- Nest application → Applications lifecycle: serves
- Applications lifecycle → Application aggregate: manages
- Organizations and branches → Academic master data: scopes
- Organizations and branches → Applications lifecycle: scopes
- Organizations and branches → CRM database schema: persists
- Applications lifecycle → CRM database schema: persists
- Lead ingestion workflow → CRM database schema: persists
- Local runtime stack → Nest application: runs