codexgautam/assetsphere

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.