Project Structure

Introduction

This document provides a detailed breakdown of the Ravenxcope frontend directory structure, file ownership conventions, and runtime-related files.

---

Root Directory

ravenxcope-frontend

.env# Local environment variables

.env.example# Documented environment variables

.gitlab-ci.yml# CI/CD pipeline definition

.prettierrc# Prettier configuration

Dockerfile# Multi-stage frontend build and Nginx runtime

README.md# Default Vite README

docker-entrypoint.sh# Writes runtime config.js before Nginx starts

eslint.config.js# ESLint flat config

index.html# Vite HTML entrypoint

nginx

package.json# Scripts and dependencies

package-lock.json# npm lockfile

yarn.lock# Yarn lockfile used by Dockerfile

postcss.config.js# PostCSS configuration

tailwind.config.js# Tailwind configuration

tsconfig.json# TypeScript project configs

vite.config.ts# Vite configuration and aliases

public# Static assets and runtime config template

src# Application source

knowledge# Frontend documentation package

Note: both package-lock.json and yarn.lock exist. The Dockerfile currently uses yarn install --frozen-lockfile, so production dependency resolution follows yarn.lock.

---

Source Directory

src

App.css# App-level styles

index.css# Global Tailwind and CSS variables

i18n.ts# i18next initialization

main.tsx# React DOM entry

app

App.tsx# Global providers and route rendering

PrivateRoutes.tsx# Private dashboard route guard

routes.tsx# Public/dashboard route metadata and sidebar nav items

components

config

core

hooks

lib

locales

modules

types

---

Feature Folder Ownership

Folder	Responsibility
modules/sensors/	Dashboard, sensor list/detail pages, metrics, enrollment command, virtual sensor CRUD and activation
modules/analytics/	Security analytics workspace, chart/filter/table partials, report export, optional AI chat
modules/users/	Organization user list page, user table partial, create/edit dialogs, delete flow
modules/roles/	Role list page, role table partial, permission dialogs, delete flow
modules/organizations/	Organization detail/profile pages and edit dialogs
modules/onboarding/	Public organization and admin-user registration pages
modules/auth/	Public login page
core/layout/	Dashboard shell, responsive sidebar, header, user menu, language switcher
core/page/	RoutePage, DataTableCard, page header/toolbar, transition, empty/loading states
components/ui/	Reusable UI primitives built on Radix UI and local styling
components/providers/	Global alert context
lib/	API, auth, constants, analytics helpers, PDF/report utilities
hooks/	Shared hooks that wrap common API reads

---

Runtime and Deployment Files

File	Role
Dockerfile	Builds static assets with Node 22 Alpine, serves them with Nginx Alpine on port 8000
docker-entrypoint.sh	Writes /usr/share/nginx/html/config.js from container environment variables
nginx/default.conf	Enables SPA fallback to index.html, static asset caching, gzip, and no-cache for config.js
public/config.js	Local/runtime config template loaded by the browser
.env.example	Documents Vite and runtime config keys

---

Naming Conventions

Type	Convention	Examples
Components	PascalCase	AnalyticsDashboard.tsx, SensorDetail.tsx
Hooks	camelCase with use prefix	useSensors, useUserPermissions
Utility modules	camelCase or domain name	analyticsFilters.ts, pdfReport.ts
Shared constants	UPPER_SNAKE object keys	PERMISSIONS.CREATE_SENSOR
Types/interfaces	PascalCase	Sensor, ApiResponse<T>, AnalyticsDashboardFilters

---

Generated or Non-Source Directories

Directory	Notes
node_modules/	Installed dependencies, not source
dist/	Vite production build output

Do not document behavior by reading built files in dist/; use source files under src/.