All systems operational

Backend Architecture

The backend is a set of server-side API routes in the Next.js app that hold the business logic, enforce permissions, and read and write Supabase.

#Purpose

Describe where business logic lives and how requests are validated and authorized.

#Architecture

API routes under the app's api tree implement the business logic for every module: CRM, projects, finance, HR, support, SEO, social, automation, reports, CMS, and administration.

Each route authenticates the caller from their Supabase session, checks role-based permissions, validates input, then reads or writes the database. Standard error responses use a small set of error codes.

#How it works

1

Authenticate

Resolve the caller and their organization from the session.
2

Authorize

Check the caller's role (for example, admin/CEO for org management).
3

Validate

Validate the request body/params before acting.
4

Act & respond

Read/write Supabase and return data or a coded error.

#Implementation notes

  • Permission helpers gate privileged actions (for example, only CEO/admin can manage the organization; CEO/admin/manager can decide timesheets).
  • Writes that must bypass RLS (e.g., notifications) use the admin client in trusted server code only.
  • Input is schema-validated; failures return a bad_request error.

#Limitations

Known limitations

  • The API is organized per feature; there is no separate microservice per module — logic is co-located in the Next.js app.
  • The public, externally consumable API is a small read surface (see Public API); most routes are internal to the app.

#Security considerations

Security

  • Every route must scope data to the caller's organization.
  • The service-role key bypasses RLS and is restricted to server code.
  • Return generic coded errors; avoid leaking internal detail.

#Best practices

  • Authenticate, authorize, validate, then act — in that order.
  • Reuse the permission helpers rather than re-checking roles ad hoc.
  • Keep responses consistent with the shared error codes.
Authorization & Isolation

Roles & RLS.

Error Codes

Response codes.

Public API

External surface.

Still need help?

Can’t find what you’re looking for? The DevSphere OS team is happy to help.

Contact Support