# What You’ll Build (and Why It Matters)#
A solid React admin dashboard architecture is not about picking a UI kit. It is about reducing risk in a B2B environment where mistakes are expensive: data leaks, broken compliance trails, and permission regressions that only show up in production.
This guide gives you a practical blueprint for B2B admin panels with:
- Information architecture that scales beyond 10 screens
- Permission-driven navigation and UI
- A production-ready audit log event model
- Feature flags that work with RBAC, not against it
- Clear module boundaries and testing approaches for permissioned routes
For a broader SaaS-focused view, also read: Next.js B2B SaaS admin panel architecture with RBAC and audit logs. For module design patterns, see: React modern frontend architecture with feature slices and modules.
# Assumptions and Non-Negotiables#
Admin dashboards are “internal” only until they are not. Treat them like public apps with stronger controls.
| Area | Recommendation | Why |
|---|---|---|
| Auth | OIDC or JWT session with short-lived access tokens | Reduces blast radius of token leaks |
| Authorization | Enforced on backend for every request | Frontend checks are not security |
| Frontend RBAC | Mirrored permissions to drive UI | Prevents confusing UX and reduces support load |
| Audit logs | Immutable, append-only | Compliance and incident response |
| Flags | Server-driven, cached client-side | Safe rollouts and tenant-specific features |
| Testing | Permissioned routes + API auth tests | Prevents regressions during refactors |
⚠️ Warning: Hiding buttons is not authorization. If the API accepts a forbidden action, your admin panel is already compromised.
# Information Architecture That Scales#
Most admin panels fail because they grow like a kitchen junk drawer: each new feature adds a menu item and a route, and the result is a navigation tree nobody understands.
A scalable information architecture starts with domain-based grouping, not screen-based grouping.
Define Domains, Not Pages#
Common B2B admin domains:
- Organization and tenants
- Users, roles, permissions
- Billing and subscriptions
- Data management or catalog
- Integrations and webhooks
- Security, audit logs, settings
- Support tooling
A good signal your domain boundaries are right: each domain can be owned by a team and deployed behind a feature flag without breaking others.
Navigation Model: Stable Top-Level, Flexible Children#
Keep top-level navigation stable. In most B2B products, 6 to 9 top-level sections is a practical ceiling; beyond that, users rely on search more than menus.
| Navigation layer | What it contains | Changes frequency |
|---|---|---|
| Top-level | Domains: Users, Billing, Integrations | Rarely |
| Second-level | Workflows: Invite, Roles, API keys | Sometimes |
| Deep pages | Entity-specific screens: user details, invoice details | Often |
A Practical Route Map Structure#
Use a route map that is data-driven and permission-aware. It becomes the single place where you reason about visibility, access, and breadcrumbs.
export type AppRoute = {
id: string;
path: string;
label: string;
navGroup?: string;
requiredPermissions?: string[];
requiredFlags?: string[];
children?: AppRoute[];
};
export const routes: AppRoute[] = [
{
id: "users",
path: "/users",
label: "Users",
navGroup: "Identity",
requiredPermissions: ["users.read"],
children: [
{
id: "user-details",
path: "/users/:userId",
label: "User details",
requiredPermissions: ["users.read"],
},
],
},
];This pays off when you add:
- A new tenant plan that hides Billing
- A compliance feature that adds Audit Logs
- A role change that removes user management access
💡 Tip: Treat the route map as a product artifact. Keep labels, groups, and breadcrumbs in one place to avoid “navigation drift” between menus and pages.
# RBAC Blueprint: Permission-Driven UI Without Chaos#
RBAC typically fails in frontend code because permission checks are scattered. The fix is to centralize permission semantics and keep UI logic declarative.
RBAC Model: Roles Are UX, Permissions Are Control#
Use permissions as the atomic unit. Roles are sets of permissions for easier admin management.
| Concept | Example | Stored where |
|---|---|---|
| Permission | users.invite, billing.update | Backend policy store |
| Role | Admin, Billing manager | Backend, tenant-scoped |
| Assignment | User has roles in tenant | Backend |
| Effective permissions | Flattened permission list | Backend response on login and refresh |
In most B2B SaaS, permissions are tenant-scoped. Do not treat “Admin” as global unless your product truly is single-tenant.
Centralize Permission Checks#
Create a small authorization surface in the frontend:
can(permission)for single permission checkscanAll([...])for strict actionscanAny([...])for UI sections
export type Permission = string;
export function createAbility(effective: Permission[]) {
const set = new Set(effective);
return {
can: (p: Permission) => set.has(p),
canAll: (ps: Permission[]) => ps.every((p) => set.has(p)),
canAny: (ps: Permission[]) => ps.some((p) => set.has(p)),
};
}Permission-Driven Navigation#
Navigation should be derived from the route map plus:
- effective permissions
- enabled feature flags
- current tenant context
export function filterRoutesForUser(
allRoutes: AppRoute[],
ability: { canAll: (ps: string[]) => boolean },
flags: { hasAll: (fs: string[]) => boolean }
) {
return allRoutes
.filter((r) => !r.requiredPermissions || ability.canAll(r.requiredPermissions))
.filter((r) => !r.requiredFlags || flags.hasAll(r.requiredFlags))
.map((r) => ({
...r,
children: r.children ? filterRoutesForUser(r.children, ability, flags) : undefined,
}));
}Permission-Driven UI: One Wrapper, Many Benefits#
Use a small RequirePermission wrapper for conditional rendering. Keep it dumb and predictable.
type RequirePermissionProps = {
all?: string[];
any?: string[];
fallback?: React.ReactNode;
children: React.ReactNode;
};
export function RequirePermission(props: RequirePermissionProps) {
const ability = useAbility();
const okAll = props.all ? ability.canAll(props.all) : true;
const okAny = props.any ? ability.canAny(props.any) : true;
if (!okAll || !okAny) return props.fallback ?? null;
return props.children;
}Use it for:
- action buttons
- dangerous controls
- entire panels inside a page
Do not use it as a “security boundary.” That boundary is the API.
# Feature Flags: Safe Rollouts and Tenant Variants#
Feature flags in admin dashboards are not optional once you have multiple tenants, pricing tiers, or staged rollouts. They let you ship code to production without exposing it.
The Rule: Flags Gate Availability, Permissions Gate Access#
A practical combined rule for UI is:
- Show a feature only if the flag is enabled
- Allow usage only if the permission is granted
- For routes: enforce both
| Scenario | Flag | Permission | Result |
|---|---|---|---|
| Feature in beta | Off | Granted | Hidden and inaccessible |
| Tenant paid add-on | On | Not granted | Visible only if you want upsell UI, but actions blocked |
| Normal feature | On | Granted | Full access |
If you want upsell UX, separate “view upsell” from “use feature” permissions, or use a route variant like /integrations showing limited content.
ℹ️ Note: Keep flags server-driven for tenant correctness. Client-only flags are fine for UI experiments but not for plan enforcement.
Minimal Flag Client#
A simple approach:
- Fetch flags on boot or tenant switch
- Cache in memory
- Refresh on interval or when you receive a 409 or 412 from the backend signaling stale config
export type FlagKey = string;
export function createFlagSet(enabled: FlagKey[]) {
const set = new Set(enabled);
return {
has: (k: FlagKey) => set.has(k),
hasAll: (ks: FlagKey[]) => ks.every((k) => set.has(k)),
};
}# Audit Logs: Event Model You Can Actually Use in Incidents#
Audit logs are only valuable if they answer who did what, when, where, and what changed. Many teams log “User updated settings” and call it a day, then cannot investigate a real incident.
Audit Log Event Model#
Store audit events as immutable records. Avoid “free-form message only.” Make it queryable.
| Field | Type | Example | Why it matters |
|---|---|---|---|
| id | string | evt_01J... | Stable reference |
| occurredAt | ISO datetime | 2026-11-07T10:30:12Z | Timeline reconstruction |
| tenantId | string | tnt_123 | Multi-tenant isolation |
| actor | object | user id, type, email | Attribution |
| action | string | users.invite | Aggregation and filters |
| entity | object | type user, id usr_9 | Trace impact |
| outcome | string | success or denied | Security analysis |
| ip | string | 203.0.113.9 | Investigation |
| userAgent | string | Mozilla/... | Forensics |
| requestId | string | req_abc | Correlate with app logs |
| changes | object | before/after subset | Understand what changed |
| metadata | object | plan, role id, reason | Business context |
Example Audit Event Payload#
Keep diffs minimal. Log only fields that changed, and avoid sensitive values.
{
"occurredAt": "2026-11-07T10:30:12Z",
"tenantId": "tnt_123",
"actor": { "type": "user", "id": "usr_1", "email": "ops@acme.com" },
"action": "roles.update",
"entity": { "type": "role", "id": "role_billing_manager" },
"outcome": "success",
"requestId": "req_c9f2a",
"ip": "203.0.113.9",
"changes": {
"permissions": {
"before": ["billing.read"],
"after": ["billing.read", "billing.update"]
}
},
"metadata": { "reason": "Access needed for subscription changes" }
}Audit Log UI: Filtering That Supports Real Work#
In practice, the most-used filters are:
- time range
- actor
- action
- entity type and id
- outcome denied vs success
Add deep links from entity pages. Example: from User details, a link “View audit events for this user” that filters by entity.type = user and entity.id = usr_9.
🎯 Key Takeaway: Design the audit log schema for investigations, not for dashboards. Queryability beats pretty messages.
# Scalable Modules and Component Boundaries#
Admin panels grow fast. If you do not draw boundaries early, you end up with shared components that become global dependencies and slow down delivery.
A practical module boundary is: a domain slice owns its routes, API calls, UI state, and permission requirements.
Suggested Folder Layout#
Avoid a flat components folder that becomes a dumping ground. Use feature modules and a thin app shell.
| Layer | Owns | Must not own |
|---|---|---|
| app-shell | router, layout, nav, providers | domain logic |
| modules or features | pages, components, hooks, api clients for domain | global UI primitives |
| shared ui | buttons, inputs, table, modal | business rules |
| shared core | auth client, ability, flags, http client | feature-specific endpoints |
Example structure:
src/app-shell/src/shared/core/ability/src/shared/core/flags/src/shared/ui/src/modules/users/src/modules/billing/src/modules/audit-log/
For a deeper dive into modularization patterns, see: React modern frontend architecture with feature slices and modules.
Define Module Contracts Explicitly#
Each module should expose:
- route definitions
- navigation items
- optional sidebar fragments
- permission list used by the module
That keeps app-shell simple: it composes modules, filters by ability and flags, and renders.
# Permissioned Routes: Patterns That Don’t Break During Refactors#
There are two access control points for routes:
- 1Navigation should not show routes a user cannot access.
- 2Router must still guard direct URL access.
Route Guard Strategy#
A reliable pattern:
- Each route has
requiredPermissionsandrequiredFlags - Router checks them before rendering the page component
- Unauthorized goes to a dedicated 403 page, not a blank screen
type GuardedRouteProps = {
requiredPermissions?: string[];
requiredFlags?: string[];
children: React.ReactNode;
};
export function GuardedRoute(props: GuardedRouteProps) {
const ability = useAbility();
const flags = useFlags();
const okPerms = props.requiredPermissions ? ability.canAll(props.requiredPermissions) : true;
const okFlags = props.requiredFlags ? flags.hasAll(props.requiredFlags) : true;
if (!okFlags) return <NotFoundPage />;
if (!okPerms) return <ForbiddenPage />;
return props.children;
}Use Not Found for disabled flags to avoid “leaking” unreleased features, and Forbidden for permission issues where the feature exists but the user cannot use it.
# Testing Blueprint: Permissioned Routes and UI Controls#
Permission logic is notoriously brittle because it spreads across routes, nav, buttons, and API calls. Your test strategy should target the decision points, not just snapshots.
For a complete testing setup with Vitest, React Testing Library, and MSW, see: React testing strategy with Vitest, React Testing Library, and MSW.
What to Test (High Value, Low Maintenance)#
| Test type | Focus | Example assertion |
|---|---|---|
| Unit tests | ability and flag logic | canAll true only when all present |
| Component tests | conditional UI | “Invite user” button hidden without users.invite |
| Router tests | permissioned routes | navigating to /billing redirects to 403 |
| Integration tests with MSW | end-to-end flows | API returns 403, UI shows error state |
| API tests | server authorization | forbidden action rejected regardless of UI |
Example: Testing a Permissioned Route#
Use an in-memory router, inject auth state, and assert correct page.
import { render, screen } from "@testing-library/react";
import { MemoryRouter } from "react-router-dom";
import { App } from "./App";
test("blocks billing route without permission", async () => {
render(
<MemoryRouter initialEntries={["/billing"]}>
<TestProviders auth={{ permissions: ["users.read"] }}>
<App />
</TestProviders>
</MemoryRouter>
);
expect(await screen.findByText("Forbidden")).toBeInTheDocument();
});Keep TestProviders as the single entry point to mock:
- effective permissions
- enabled flags
- tenant context
⚠️ Warning: If your tests mock permission checks by mocking
can()everywhere, you are not testing real behavior. Prefer injecting effective permissions and letting the ability layer compute decisions.
Example: Testing a Permission-Driven Button#
import { render, screen } from "@testing-library/react";
import { UserToolbar } from "./UserToolbar";
test("hides Invite button without users.invite", () => {
render(
<TestProviders auth={{ permissions: ["users.read"] }}>
<UserToolbar />
</TestProviders>
);
expect(screen.queryByText("Invite user")).toBeNull();
});Contract Tests Between Frontend and Backend#
The most common production bug is mismatch between permission strings and backend enforcement. Add a lightweight contract:
- frontend permission constants live in one place
- backend exposes
/me/permissionsand/me/flags - CI validates that frontend permission keys are a subset of backend-known keys
This can be as simple as a JSON list produced by backend during build or a test endpoint in staging.
# Putting It Together: A Practical Blueprint#
Use this sequence to implement a new module safely:
- 1Add domain module with routes, required permissions, required flags.
- 2Add API client methods for that domain and ensure backend enforces authorization.
- 3Add navigation items derived from route definitions.
- 4Add audit log events for key actions, especially destructive or permission-related changes.
- 5Add permission-driven UI wrappers for controls.
- 6Add tests at three levels: ability, route guard, and at least one integration flow.
This is how you keep velocity while preventing permission regressions when the dashboard grows from 15 to 150 screens.
# Key Takeaways#
- Treat the route map as data: include labels, permissions, and flags, then derive navigation and breadcrumbs from it.
- Enforce authorization on the backend, and mirror effective permissions in the frontend to drive a permission-driven UI.
- Design audit log events for investigations: actor, action, entity, outcome, request id, and minimal diffs.
- Use feature flags to gate availability and permissions to gate access; require both for sensitive routes.
- Split the dashboard into domain modules that own routes, API calls, and permission requirements to avoid cross-feature coupling.
- Test permissioned routes with an in-memory router and injected effective permissions, then back it up with API authorization tests.
# Conclusion#
A maintainable React admin dashboard architecture is a system: information architecture, RBAC-driven navigation, auditability, flags, module boundaries, and tests all reinforce each other. If you implement only one part, the weak link becomes your source of incidents and support tickets.
If you want a proven baseline for your B2B admin panel, Samioda can help you define the module boundaries, RBAC model, audit event schema, and a testing strategy that prevents permission regressions while your product scales. Reach out via Samioda and we’ll turn this blueprint into a working codebase.
FAQ
Founder & Senior Developer at Samioda. 8+ years building React, Next.js, Flutter and n8n automation solutions for clients across Europe.
More in Web Development
All →Next.js App Router Session Auth: Cookie Sessions, Middleware, and Refresh Patterns
A practical guide to Next.js App Router session authentication using httpOnly cookie sessions, middleware guards, and refresh or rotation patterns — with secure logout, CSRF guidance, and Vercel runtime notes.
Real-Time Notifications in Next.js (App Router): SSE vs WebSockets, Fanout, and Delivery Guarantees
Build production-grade Next.js real-time notifications with the App Router. Compare SSE vs WebSockets, design inbox persistence and read states, scale fanout safely, and add polling fallbacks with React Query or SWR.
Next.js Multi-Tenant Authentication in the App Router: Tenant Resolution, Switching, and Security
A practical guide to Next.js multi-tenant authentication in the App Router: tenant resolution via subdomain, path, or header, session scoping, safe tenant switching UX, and code patterns that prevent cross-tenant data leaks.
Need help with your project?
We build custom solutions using the technologies discussed in this article. Senior team, fixed prices.
Related Articles
Next.js B2B SaaS Admin Panel Architecture: RBAC, Audit Logs, Impersonation, and Safe Bulk Actions
A practical reference architecture for Next.js admin panels: permission modeling, audit logs, secure impersonation, and safety checklists for bulk actions, exports, and PII handling.
React Multi-Step Forms at Scale: Save Draft, Resume Later, Validation, and Step Navigation
A practical guide to building a React multi step form that supports draft saving, cross-device resume, conditional steps, and robust validation using React Hook Form + Zod with server-side persistence and analytics.
React Component Contract Testing: MSW + Storybook as Living API Mocks
A practical guide to React component contract testing using shared MSW handlers across Storybook and automated tests to prevent mock drift, flaky UI, and regressions in CI.