Architecture

Introduction

This document describes the Ravenxcope frontend architecture, the dependency direction between layers, the runtime initialization flow, and important design decisions that shape the codebase.

---

Architecture Pattern

The frontend follows a practical feature-oriented React architecture. The route tree and navigation metadata are centralized in src/app/routes.tsx, global layout lives in src/core/layout, reusable route/page scaffolding lives in src/core/page, data access is centralized in src/lib/api.ts, and feature screens live under src/modules.

---

Layer Responsibilities

Layer	Main Files / Folders	Responsibility
Entry	src/main.tsx	Mount React, import global CSS, initialize i18n
Routing	src/app/App.tsx, src/app/routes.tsx, src/app/PrivateRoutes.tsx	Define public/private routes, dashboard route metadata, navigation items, and route guard
Layout	src/core/layout/	App shell, sidebar, header, user dropdown, language switcher, mobile drawer, footer/content frame
Page Scaffold	src/core/page/	Route page wrapper, page header/toolbar, table cards, empty/loading states, transitions
Feature UI	src/modules/{sensors,users,roles,organizations,analytics}	Route-level pages, feature-specific partials, dialogs, and domain sub-flows
Shared UI	src/components/ui/	Button, card, dialog, table, select, sheet, tooltip, and other primitives
Data Hooks	src/hooks/useApi.ts	Small data-fetching hooks for common resource reads
API Client	src/lib/api.ts	Axios instance, interceptors, endpoint groups, query serialization
Auth	src/lib/auth.ts	Cookie session helpers and permission helpers
Config	src/config/appConfig.ts	Runtime config parsing, validation, and freezing
Types	src/types/index.ts	API payload, entity, filter, analytics, and component types
Localization	src/i18n.ts, src/locales/	i18next setup and message catalogs

---

Dependency Direction

Current dependency rules:

• Feature components call the centralized api object rather than creating ad-hoc Axios clients.
• apiClient attaches bearer tokens through auth.getToken().
• appConfig is the only source of sanitized runtime configuration.
• Shared UI primitives do not call backend APIs.
• Types are centralized in src/types/index.ts, not colocated per feature.

---

Runtime Initialization

The browser boot sequence is:

1. Bundle Loading: index.html loads the built script bundle and config.js.
2. Setup Initialization: src/main.tsx imports src/i18n.ts, src/index.css, and App.
3. Localization: src/i18n.ts loads English and Indonesian resources, selects language, and persists changes.
4. App Mounting: App mounts global providers, router, and core layout components.
5. Auth Guard: Private dashboard routes call auth.isAuthenticated() before rendering.
6. Shell Hydration: The dashboard app shell fetches current user data and renders navigation.
7. Feature Loading: Feature views fetch backend data through api or custom hooks.

---

Important Design Decisions

1. Single centralized API object - src/lib/api.ts groups all backend calls by domain.
2. Cookie-based session storage - Access token, user ID, and organization ID are stored through js-cookie.
3. Runtime config over rebuilds - window.__APP_CONFIG__ allows configuration changes without rebuilding.
4. Manual async hooks instead of React Query - The app uses useState and useEffect for data fetching.
5. Route-level dashboard shell - /dashboard renders AppShell with a nested Outlet.
6. Feature flags - Analytics chat UI checks both frontend flags and backend status.
7. Flexible response handling - Components tolerate multiple response shapes during contract stabilization.

---

Known Architecture Debt

Area	Issue	Impact
App shell composition	AppShell.tsx centralizes standard vs workspace layout	Keep as only global layout boundary
Route-level page organization	Route pages live under modules/*/pages	Continue keeping orchestration in pages
Large feature views	Analytics views have substantial data orchestration	Focus on domain hooks for further extraction
Reusable page chrome	RoutePage and DataTableCard are standard scaffolds	Use for new management pages
Layout consistency	List pages use shared table scaffolds	Keep future CRUD pages aligned
Route constants	ROUTES and dashboardRoutes cover navigation	Centralize paths in src/lib/constants.ts
State/data fetching	Server state managed manually	Duplicated loading/error logic
API surface	All endpoints in one large api.ts	High-churn file
Type organization	All domain types in one types/index.ts	Harder to navigate
Response contracts	Multiple response shapes supported	Potential for contract drift
Tests	No dedicated frontend test suite	Regression risk for core flows