# codexgautam/assetsphere architecture

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

- Interactive diagram: https://gitdiagram.com/codexgautam/assetsphere
- Repository: https://github.com/codexgautam/assetsphere

## Overview

1. **Overall shape**
   AssetSphere is a single Next.js 15 application using the App Router. There is no separate backend service; the same Node.js server renders pages and serves `/api/*` route handlers. The architecture is split into route-level UI, API handlers, business services, and Mongoose models.

2. **Primary domain boundary: multi-tenant organisation**
   Almost every business object is scoped to an organisation: assets, bookings, categories, members, notifications, audit logs, and analytics. The platform has three roles with distinct scopes: `SUPERADMIN` at the platform level, `ORG_ADMIN` within one organisation, and `MEMBER` for end users inside an organisation.

3. **Presentation layer**
   The `src/app` tree is organised by route groups and functional areas:
   - `(landing)` for public marketing content
   - `(auth)` for login/register
   - `dashboard`, `assets`, `bookings`, `notifications`, `onboard`, and `invite/[token]` for member-facing flows
   - `admin/*` for organisation administration
   - `superadmin/*` for platform moderation
   Shared UI lives in `src/components`, grouped by domain such as assets, bookings, dashboard, landing, charts, forms, and design-system primitives.

4. **Access control and session enforcement**
   Authentication is handled by NextAuth v5 with JWT sessions. `src/middleware.ts` enforces route protection at the edge for private areas, while API handlers perform their own session and role checks. This creates two security boundaries: page navigation protection and server-side authorization for data access.

5. **API layer as the orchestration boundary**
   All mutations and most reads go through `/api/*` route handlers under `src/app/api`. These handlers are the coordination point between validation, permissions, services, and persistence. The API is split by domain: assets, bookings, categories, organisations, notifications, audit logs, analytics, auth, invite, health, admin users, and superadmin operations.

6. **Business logic layer**
   `src/services` contains the domain workflows that sit between route handlers and database models. The service layer covers assets, bookings, categories, users, notifications, and audit logging. This is where state transitions, side effects, and cross-entity updates are centralized instead of being spread across route handlers.

7. **Persistence model**
   `src/models` contains the Mongoose schemas for the core domain entities: user, organisation, asset, category, booking, invite, notification, and audit log. MongoDB is the system of record, and `src/lib/db.ts` provides the shared connection layer. The data model supports the multi-tenant boundary and booking lifecycle state.

8. **Booking workflow and asset availability**
   The booking subsystem is the most important transactional flow. Members create booking requests, admins approve/reject/issue/return them, and asset availability is adjusted automatically when statuses change. This means bookings are not just records; they drive inventory accounting for available quantity and overdue state.

9. **Invites, onboarding, and membership management**
   Organisation onboarding starts with a public application flow, then platform approval. After approval, organisation admins can invite members via tokenised email links with TTL-based invite tokens. Accepting an invite creates or connects the user and joins them to the organisation, making invite handling a key boundary between public onboarding and tenant membership.

10. **Notifications, audit logs, and operational traceability**
   Notifications are created for important lifecycle events such as booking status changes and invites, and they surface in an in-app notification center with unread state. Audit logs capture immutable records of significant actions with actor and metadata. Together, these provide both user-facing feedback and administrative traceability.

11. **Analytics and admin dashboard**
   The org admin dashboard is powered by dedicated analytics endpoints for summary KPIs, utilisation, category distribution, and booking status breakdown. These endpoints feed chart components under `src/components/charts` and stat cards in the dashboard. The analytics subsystem is read-heavy and derived from the same operational MongoDB data.

12. **External integrations**
   Three integrations materially affect the architecture:
   - **SendGrid** for email delivery around invites and approvals
   - **Cloudinary** for asset image uploads
   - **QR generation/scanning** for asset identification and browser-based scanning
   These are optional or gracefully degraded where noted, but they extend the asset and onboarding workflows beyond the database.

13. **Validation and shared contract layer**
   `src/validators` holds Zod schemas for auth, assets, bookings, and categories, so request validation is explicit and consistent across API endpoints. `src/types` and `src/constants` provide shared enums and typed contracts used by both UI and server code, reducing drift between the routes, services, and components.

14. **Deployment and runtime assumptions**
   The app is designed for deployment as a single Next.js server, commonly on Vercel, with MongoDB Atlas in production. Docker Compose supports local development by running the app alongside MongoDB. The architecture does not depend on any separate backend process or message queue; side effects happen synchronously inside API requests.

Main entry points: [`src/app/api/assets/route.ts`](https://github.com/codexgautam/assetsphere/blob/main/src/app/api/assets/route.ts) (Assets API), [`src/services/booking-service.ts`](https://github.com/codexgautam/assetsphere/blob/main/src/services/booking-service.ts) (Services), [`src/app/api/bookings/route.ts`](https://github.com/codexgautam/assetsphere/blob/main/src/app/api/bookings/route.ts) (Bookings API), [`src/lib/permissions.ts`](https://github.com/codexgautam/assetsphere/blob/main/src/lib/permissions.ts) (Permissions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_landing["Landing<br/>public pages<br/>[page.tsx]"]
  node_auth["Auth<br/>login/register<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>org overview<br/>[page.tsx]"]
  node_assets_pages["Assets<br/>asset UI<br/>[page.tsx]"]
  node_bookings_pages["Bookings<br/>booking UI<br/>[page.tsx]"]
  node_notifications_pages["Notifications<br/>in-app inbox<br/>[page.tsx]"]
  node_admin_pages["Org Admin<br/>admin console<br/>[page.tsx]"]
  node_superadmin_pages["Superadmin<br/>platform console<br/>[page.tsx]"]
end

subgraph group_api["API"]
  node_assets_api{{"Assets API<br/>route handlers<br/>[route.ts]"}}
  node_bookings_api{{"Bookings API<br/>route handlers<br/>[route.ts]"}}
  node_admin_api{{"Admin API<br/>route handlers<br/>[route.ts]"}}
  node_analytics_api{{"Analytics API<br/>read endpoints<br/>[route.ts]"}}
  node_notifications_api{{"Notifications API<br/>route handlers<br/>[route.ts]"}}
  node_invite_api{{"Invite API<br/>token flow<br/>[route.ts]"}}
  node_orgs_api{{"Orgs API<br/>approval flow<br/>[route.ts]"}}
  node_superadmin_api{{"Superadmin API<br/>platform ops<br/>[route.ts]"}}
end

subgraph group_core["Core"]
  node_middleware{{"Middleware<br/>edge auth guard<br/>[middleware.ts]"}}
  node_auth_core["Auth Core<br/>nextauth session<br/>[auth.ts]"]
  node_permissions["Permissions<br/>role checks<br/>[permissions.ts]"]
  node_db[("Database<br/>mongo connection<br/>[db.ts]")]
  node_services["Services<br/>domain workflows<br/>[booking-service.ts]"]
  node_models[("Models<br/>mongoose schemas<br/>[booking.ts]")]
  node_validators["Validators<br/>zod schemas<br/>[booking.ts]"]
  node_integrations["Integrations<br/>external services<br/>[sendgrid.ts]"]
end

node_landing -->|"entry"| node_auth
node_auth -->|"sessions"| node_auth_core
node_dashboard -->|"feeds charts"| node_analytics_api
node_assets_pages -->|"reads/writes"| node_assets_api
node_bookings_pages -->|"reads/writes"| node_bookings_api
node_notifications_pages -->|"inbox"| node_notifications_api
node_admin_pages -->|"manage org"| node_admin_api
node_superadmin_pages -->|"moderate"| node_superadmin_api
node_middleware -->|"protects"| node_dashboard
node_middleware -->|"protects"| node_assets_pages
node_middleware -->|"protects"| node_bookings_pages
node_assets_api -->|"validates"| node_validators
node_bookings_api -->|"validates"| node_validators
node_orgs_api -->|"validates"| node_validators
node_assets_api -->|"authorizes"| node_permissions
node_bookings_api -->|"authorizes"| node_permissions
node_admin_api -->|"authorizes"| node_permissions
node_superadmin_api -->|"authorizes"| node_permissions
node_assets_api -->|"orchestrates"| node_services
node_bookings_api -->|"orchestrates"| node_services
node_admin_api -->|"orchestrates"| node_services
node_analytics_api -->|"reads"| node_db
node_services -->|"persists"| node_db
node_services -->|"uses"| node_models
node_models -->|"stores"| node_db
node_invite_api -->|"emails"| node_integrations
node_assets_api -->|"uploads/qr"| node_integrations
node_orgs_api -->|"emails"| node_integrations

click node_landing "https://github.com/codexgautam/assetsphere/blob/main/src/app/(landing)/page.tsx"
click node_auth "https://github.com/codexgautam/assetsphere/blob/main/src/app/(auth)/login/page.tsx"
click node_dashboard "https://github.com/codexgautam/assetsphere/blob/main/src/app/dashboard/page.tsx"
click node_assets_pages "https://github.com/codexgautam/assetsphere/blob/main/src/app/assets/page.tsx"
click node_bookings_pages "https://github.com/codexgautam/assetsphere/blob/main/src/app/bookings/page.tsx"
click node_notifications_pages "https://github.com/codexgautam/assetsphere/blob/main/src/app/notifications/page.tsx"
click node_admin_pages "https://github.com/codexgautam/assetsphere/blob/main/src/app/admin/page.tsx"
click node_superadmin_pages "https://github.com/codexgautam/assetsphere/blob/main/src/app/superadmin/orgs/page.tsx"
click node_middleware "https://github.com/codexgautam/assetsphere/blob/main/src/middleware.ts"
click node_auth_core "https://github.com/codexgautam/assetsphere/blob/main/src/lib/auth.ts"
click node_permissions "https://github.com/codexgautam/assetsphere/blob/main/src/lib/permissions.ts"
click node_db "https://github.com/codexgautam/assetsphere/blob/main/src/lib/db.ts"
click node_services "https://github.com/codexgautam/assetsphere/blob/main/src/services/booking-service.ts"
click node_models "https://github.com/codexgautam/assetsphere/blob/main/src/models/booking.ts"
click node_validators "https://github.com/codexgautam/assetsphere/blob/main/src/validators/booking.ts"
click node_integrations "https://github.com/codexgautam/assetsphere/blob/main/src/lib/sendgrid.ts"
click node_assets_api "https://github.com/codexgautam/assetsphere/blob/main/src/app/api/assets/route.ts"
click node_bookings_api "https://github.com/codexgautam/assetsphere/blob/main/src/app/api/bookings/route.ts"
click node_admin_api "https://github.com/codexgautam/assetsphere/blob/main/src/app/api/orgs/members/route.ts"
click node_analytics_api "https://github.com/codexgautam/assetsphere/blob/main/src/app/api/analytics/summary/route.ts"
click node_notifications_api "https://github.com/codexgautam/assetsphere/blob/main/src/app/api/notifications/route.ts"
click node_invite_api "https://github.com/codexgautam/assetsphere/blob/main/src/app/api/invite/[token]/route.ts"
click node_orgs_api "https://github.com/codexgautam/assetsphere/blob/main/src/app/api/orgs/route.ts"
click node_superadmin_api "https://github.com/codexgautam/assetsphere/blob/main/src/app/api/superadmin/orgs/route.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_landing,node_auth,node_dashboard,node_assets_pages,node_bookings_pages,node_notifications_pages,node_admin_pages,node_superadmin_pages toneBlue
class node_assets_api,node_bookings_api,node_admin_api,node_analytics_api,node_notifications_api,node_invite_api,node_orgs_api,node_superadmin_api toneAmber
class node_middleware,node_auth_core,node_permissions,node_db,node_services,node_models,node_validators,node_integrations toneMint
```

## Components

### Presentation

App Router pages and shared UI.

- [Landing](https://github.com/codexgautam/assetsphere/blob/main/src/app/(landing)/page.tsx): public pages · Marketing and public-facing entry pages. · `src/app/(landing)/page.tsx`
- [Auth](https://github.com/codexgautam/assetsphere/blob/main/src/app/(auth)/login/page.tsx): login/register · Authentication entry pages. · `src/app/(auth)/login/page.tsx`
- [Dashboard](https://github.com/codexgautam/assetsphere/blob/main/src/app/dashboard/page.tsx): org overview · Member and admin landing area. · `src/app/dashboard/page.tsx`
- [Assets](https://github.com/codexgautam/assetsphere/blob/main/src/app/assets/page.tsx): asset UI · Asset listing and detail pages. · `src/app/assets/page.tsx`
- [Bookings](https://github.com/codexgautam/assetsphere/blob/main/src/app/bookings/page.tsx): booking UI · Booking request and review pages. · `src/app/bookings/page.tsx`
- [Notifications](https://github.com/codexgautam/assetsphere/blob/main/src/app/notifications/page.tsx): in-app inbox · Notification center for users. · `src/app/notifications/page.tsx`
- [Org Admin](https://github.com/codexgautam/assetsphere/blob/main/src/app/admin/page.tsx): admin console · Organisation administration pages. · `src/app/admin/page.tsx`
- [Superadmin](https://github.com/codexgautam/assetsphere/blob/main/src/app/superadmin/orgs/page.tsx): platform console · Platform moderation pages. · `src/app/superadmin/orgs/page.tsx`

### API

Route handlers that coordinate requests.

- [Assets API](https://github.com/codexgautam/assetsphere/blob/main/src/app/api/assets/route.ts): route handlers · Asset CRUD and uploads orchestration. · `src/app/api/assets/route.ts`
- [Bookings API](https://github.com/codexgautam/assetsphere/blob/main/src/app/api/bookings/route.ts): route handlers · Booking lifecycle and availability updates. · `src/app/api/bookings/route.ts`
- [Admin API](https://github.com/codexgautam/assetsphere/blob/main/src/app/api/orgs/members/route.ts): route handlers · Organisation admin and member management endpoints. · `src/app/api/orgs/members/route.ts`
- [Analytics API](https://github.com/codexgautam/assetsphere/blob/main/src/app/api/analytics/summary/route.ts): read endpoints · Derived KPI, utilisation, and status summaries. · `src/app/api/analytics/summary/route.ts`
- [Notifications API](https://github.com/codexgautam/assetsphere/blob/main/src/app/api/notifications/route.ts): route handlers · Notification listing and read-state updates. · `src/app/api/notifications/route.ts`
- [Invite API](https://github.com/codexgautam/assetsphere/blob/main/src/app/api/invite/[token]/route.ts): token flow · Invite creation and acceptance boundary. · `src/app/api/invite/[token]/route.ts`
- [Orgs API](https://github.com/codexgautam/assetsphere/blob/main/src/app/api/orgs/route.ts): approval flow · Organisation application, approval, rejection, and membership endpoints. · `src/app/api/orgs/route.ts`
- [Superadmin API](https://github.com/codexgautam/assetsphere/blob/main/src/app/api/superadmin/orgs/route.ts): platform ops · Platform-level organisation moderation and seeding. · `src/app/api/superadmin/orgs/route.ts`

### Core

Shared runtime, services, models, and integration layers.

- [Middleware](https://github.com/codexgautam/assetsphere/blob/main/src/middleware.ts): edge auth guard · Route protection for private areas. · `src/middleware.ts`
- [Auth Core](https://github.com/codexgautam/assetsphere/blob/main/src/lib/auth.ts): nextauth session · JWT session setup and auth configuration. · `src/lib/auth.ts`
- [Permissions](https://github.com/codexgautam/assetsphere/blob/main/src/lib/permissions.ts): role checks · Role and scope authorization helpers. · `src/lib/permissions.ts`
- [Database](https://github.com/codexgautam/assetsphere/blob/main/src/lib/db.ts): mongo connection · Shared MongoDB connection layer. · `src/lib/db.ts`
- [Services](https://github.com/codexgautam/assetsphere/blob/main/src/services/booking-service.ts): domain workflows · Business logic for assets, bookings, users, categories, notifications, and audit logs. · `src/services/booking-service.ts`
- [Models](https://github.com/codexgautam/assetsphere/blob/main/src/models/booking.ts): mongoose schemas · Organisation-scoped persistence models. · `src/models/booking.ts`
- [Validators](https://github.com/codexgautam/assetsphere/blob/main/src/validators/booking.ts): zod schemas · Request validation contracts for core domains. · `src/validators/booking.ts`
- [Integrations](https://github.com/codexgautam/assetsphere/blob/main/src/lib/sendgrid.ts): external services · Email, uploads, and QR tooling. · `src/lib/sendgrid.ts`

## Connections

- Landing → Auth: entry · Public users move into authentication.
- Auth → Auth Core: sessions · Login and registration use the shared NextAuth setup.
- Dashboard → Analytics API: feeds charts · Dashboard metrics are read from analytics endpoints.
- Assets → Assets API: reads/writes · Asset pages rely on API handlers for data.
- Bookings → Bookings API: reads/writes · Booking pages use the booking lifecycle API.
- Notifications → Notifications API: inbox · Notification UI loads and updates through the API.
- Org Admin → Admin API: manage org · Admin pages manage members and organisation settings.
- Superadmin → Superadmin API: moderate · Platform pages call superadmin endpoints.
- Middleware → Dashboard: protects · Private page navigation is guarded at the edge.
- Middleware → Assets: protects · Private page navigation is guarded at the edge.
- Middleware → Bookings: protects · Private page navigation is guarded at the edge.
- Assets API → Validators: validates · Asset requests are schema-validated.
- Bookings API → Validators: validates · Booking requests are schema-validated.
- Orgs API → Validators: validates · Organisation and invite requests are schema-validated.
- Assets API → Permissions: authorizes · Asset access is scoped by role and organisation.
- Bookings API → Permissions: authorizes · Booking actions enforce role and tenant checks.
- Admin API → Permissions: authorizes · Admin endpoints enforce org-admin boundaries.
- Superadmin API → Permissions: authorizes · Platform endpoints enforce superadmin access.
- Assets API → Services: orchestrates · API handlers delegate workflows to services.
- Bookings API → Services: orchestrates · Booking transitions are coordinated in services.
- Admin API → Services: orchestrates · Member and user operations flow through services.
- Analytics API → Database: reads · Analytics are derived from operational data.
- Services → Database: persists · Domain workflows read and write MongoDB.
- Services → Models: uses · Services operate on Mongoose models.
- Models → Database: stores · Models are backed by the shared database connection.
- Invite API → Integrations: emails · Invites are delivered through email integration.
- Assets API → Integrations: uploads/qr · Asset uploads and QR flows use external helpers.
- Orgs API → Integrations: emails · Onboarding and invite flows send email.