La Comanda System Architecture: Frontend, API, and Database

La Comanda is a three-tier web application composed of a React single-page application, an Express REST API, and a MySQL relational database — all orchestrated by Docker Compose. The frontend communicates exclusively with the backend over HTTP, the backend uses Prisma ORM to read and write data, and Clerk provides authentication as an external service that both tiers rely on for identity. This document walks through each layer in detail, including the routing structure, auth flow, color system, and internationalization setup.

System Overview

┌─────────────────────────────────────────────────────────────┐
│                        Browser                              │
│                                                             │
│   React 19 SPA (Vite)  ←→  Clerk (external auth service)   │
│   localhost:5173                                            │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTP / REST
┌────────────────────▼────────────────────────────────────────┐
│               Express 5 API Server                          │
│               localhost:3000                                │
│               Prisma ORM                                    │
└────────────────────┬────────────────────────────────────────┘
                     │ TCP / Prisma query engine
┌────────────────────▼────────────────────────────────────────┐
│               MySQL 8.0  (Docker volume: mysql_data)        │
│               localhost:3306                                │
│               Database: la_comanda                          │
└─────────────────────────────────────────────────────────────┘

Frontend

React 19 SPA built with Vite, styled with Tailwind CSS v3, routed by react-router-dom v7, authenticated via Clerk React, and internationalized with i18next.

Backend

Express 5 REST API with CORS and JSON body parsing enabled. Uses Prisma ORM to interface with MySQL. Runs on port 3000.

Database

MySQL 8.0 container with a persistent named Docker volume (mysql_data). Schema managed by Prisma migrations.

Auth

Clerk handles sign-in, session management, and token issuance. Protected routes use a ProtectedRoute wrapper built on Clerk’s SignedIn / SignedOut / RedirectToSignIn components.

Frontend

The frontend is a React 19 single-page application built and served by Vite 8. TypeScript (~6.0) is used throughout for type safety, and ESLint with the react-hooks and react-refresh plugins enforces code quality during development.

Routing

Client-side navigation is handled by react-router-dom v7 using a BrowserRouter and a flat Routes tree. The application defines eight routes:

Path	Component	Protected
`/`	`LoginPage`	No
`/dashboard`	`Dashboard`	Yes
`/tables`	`TableView`	Yes
`/kitchen`	`KitchenMonitor`	Yes
`/inventory`	`Inventory`	Yes
`/staff`	`StaffControl`	Yes
`/settings`	`Settings`	Yes
`/403`	`AccessDenied`	Yes

Every protected route is wrapped by a ProtectedRoute component defined in App.tsx:

const ProtectedRoute = ({ children }: { children: React.ReactNode }) => {
  return (
    <>
      <SignedIn>{children}</SignedIn>
      <SignedOut>
        <RedirectToSignIn />
      </SignedOut>
    </>
  );
};

The full routing tree from App.tsx:

const App: React.FC = () => {
    return (
        <BrowserRouter>
            <Routes>
                <Route path="/" element={<LoginPage />} />
                <Route path="/dashboard" element={<ProtectedRoute><Dashboard /></ProtectedRoute>} />
                <Route path="/tables" element={<ProtectedRoute><TableView /></ProtectedRoute>} />
                <Route path="/kitchen" element={<ProtectedRoute><KitchenMonitor /></ProtectedRoute>} />
                <Route path="/inventory" element={<ProtectedRoute><Inventory /></ProtectedRoute>} />
                <Route path="/staff" element={<ProtectedRoute><StaffControl /></ProtectedRoute>} />
                <Route path="/settings" element={<ProtectedRoute><Settings /></ProtectedRoute>} />
                <Route path="/403" element={<ProtectedRoute><AccessDenied /></ProtectedRoute>} />
            </Routes>
        </BrowserRouter>
    );
};

Styling

Tailwind CSS v3 is configured with darkMode: "class" and a comprehensive set of Material Design 3-inspired color tokens defined in tailwind.config.js. The design system uses semantic role names rather than raw color values, making it straightforward to apply theme changes globally. The font stack defaults to Inter across all type scales. Key color tokens from tailwind.config.js:

colors: {
  "primary":                   "#094cb2",
  "primary-container":         "#3366cc",
  "on-primary":                "#ffffff",
  "secondary":                 "#5a5f63",
  "secondary-container":       "#dfe3e8",
  "tertiary":                  "#6d5e00",
  "tertiary-container":        "#bfab49",
  "surface":                   "#faf9fa",
  "background":                "#faf9fa",
  "error":                     "#ba1a1a",
  "outline":                   "#737784",
  "surface-tint":              "#2259bf",
  // ...and more role-based tokens
}

Border radii follow a compact scale (DEFAULT: 0.125rem, lg: 0.25rem, xl: 0.5rem, full: 0.75rem) to match Material Design’s slightly rounded aesthetic.

Backend

The backend is an Express 5 server written in TypeScript and compiled by ts-node in development (via nodemon) and tsc for production builds.

Server Setup

import express from 'express';
import cors from 'cors';

const app = express();
const port = process.env.PORT || 3000;

app.use(cors());
app.use(express.json());

app.get('/', (req, res) => {
  res.json({ message: 'Welcome to La Comanda API' });
});

app.get('/api/health', (req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});

app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

Current Endpoints

Method	Path	Description
`GET`	`/`	Welcome message — confirms the API is reachable
`GET`	`/api/health`	Health check — returns `status: ok` and an ISO timestamp

The backend is under active development. Additional REST endpoints for tables, orders, inventory, and staff will be added as features are built out.

ORM

Prisma 7 is used as the ORM. The @prisma/client package is generated from the Prisma schema and used in route handlers to issue type-safe queries against MySQL. The DATABASE_URL environment variable is injected by Docker Compose at runtime.

Database

La Comanda uses MySQL 8.0 running in a dedicated Docker container. Data is persisted in a named Docker volume so it survives container restarts.

Docker Compose Services

The full docker-compose.yml defines three services:

version: '3.8'

services:
  frontend:
    build:
      context: ./frontend
    container_name: lacomanda_frontend
    ports:
      - "5173:5173"
    volumes:
      - ./frontend:/app
      - /app/node_modules
    environment:
      - VITE_API_URL=http://localhost:3000
    depends_on:
      - backend

  backend:
    build:
      context: ./backend
    container_name: lacomanda_backend
    ports:
      - "3000:3000"
    volumes:
      - ./backend:/app
      - /app/node_modules
    environment:
      - DATABASE_URL=mysql://root:rootpassword@db:3306/la_comanda
      - PORT=3000
    depends_on:
      - db

  db:
    image: mysql:8.0
    container_name: lacomanda_db
    ports:
      - "3306:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword
      - MYSQL_DATABASE=la_comanda
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:

Connection Details

Parameter	Value
Host (from backend container)	`db`
Host (from host machine)	`localhost`
Port	`3306`
Root password	`rootpassword`
Database name	`la_comanda`
Connection string	`mysql://root:rootpassword@db:3306/la_comanda`

The credentials above are development defaults included for local use only. Never deploy these values to a production or publicly accessible environment.

Auth Flow

La Comanda delegates all identity management to Clerk. The frontend is wrapped in a ClerkProvider at the application root, which makes Clerk’s hooks and components available throughout the tree.

A user navigates to any protected route (e.g., /dashboard).
The ProtectedRoute wrapper renders <SignedIn> and <SignedOut> children side-by-side.
If the Clerk session is inactive, <SignedOut> renders <RedirectToSignIn />, which redirects the browser to Clerk’s hosted sign-in flow.
After the user authenticates, Clerk redirects back to the originally requested route.
<SignedIn> now renders, and the protected page component mounts.

The useAuth hook from @clerk/clerk-react is available inside any component to access the current session token, user ID, and sign-out function when needed for API calls.

To obtain your VITE_CLERK_PUBLISHABLE_KEY, sign in to dashboard.clerk.com, create an application, and copy the key from the API Keys section. The key starts with pk_test_ for development environments.

Internationalization (i18n)

The frontend is fully internationalized using i18next (^26.3) and react-i18next (^17.0). Translation resources are stored as JSON files under src/locales/:

File	Language
`src/locales/en.json`	English
`src/locales/es.json`	Spanish

Translations are organized into namespaces that map to application sections:

Namespace	Covers
`sidebar`	Navigation menu labels
`header`	Top bar and global UI text
`login`	Authentication page content
`dashboard`	Analytics and metrics labels
`tables`	Table view and floor plan
`kitchen`	Kitchen display system
`inventory`	Inventory management interface
`staff`	Staff management panel
`settings`	System settings page
`access_denied`	403 error page content

Using the useTranslation hook with a specific namespace keeps translation keys scoped and avoids collisions as the application grows:

import { useTranslation } from 'react-i18next';

const { t } = useTranslation('dashboard');

// Usage
<h1>{t('title')}</h1>

Getting Started

Deployment

La Comanda System Architecture: Frontend, API, and Database

System Overview

Frontend

Backend

Database

Auth

Frontend

Routing

Styling

Backend

Server Setup

Current Endpoints

ORM

Database

Docker Compose Services

Connection Details

Auth Flow

Internationalization (i18n)

Build docs developers (and LLMs) love

Getting Started

Deployment

Documentation Index

​System Overview

Frontend

Backend

Database

Auth

​Frontend

​Routing

​Styling

​Backend

​Server Setup

​Current Endpoints

​ORM

​Database

​Docker Compose Services

​Connection Details

​Auth Flow

​Internationalization (i18n)

Build docs developers (and LLMs) love

System Overview

Frontend

Routing

Styling

Backend

Server Setup

Current Endpoints

ORM

Database

Docker Compose Services

Connection Details

Auth Flow

Internationalization (i18n)