This monorepo hosts three active runtimes.
backend/api
is the Express service, with business logic in
services/
, validation in
config/
and
src/middleware/
, and HTTP handlers in
routes/
. The React admin dashboard lives in
backend/dashboard
, while the Vite + TypeScript storefront is in
frontend
. Shared SQLite dumps sit in
backend/data/
, generated assets land in
uploads/
, and docs stay in
docs/
; legacy variants live in
legacy/
.
npm run install:all
(root) installs dependencies across the API, dashboard, and storefront.npm start
(root) boots API (3001), storefront (3000), and dashboard (3002) together for local work.npm run start:api
/ npm run start:frontend
/ npm run start:dashboard
focus on one surface at a time.npm run build
(root) emits production bundles for the two React apps.docker-compose -f docker-compose.development.yml up
starts the MariaDB-backed stack when you need parity with production.
API code sticks to 2-space indentation, single quotes, and CommonJS modules; keep route filenames kebab-case (
products-mariadb.js
) and service helpers camelCase. React workspaces use PascalCase components,
use*
hooks, and Tailwind utilities ordered layout → spacing → color. Run
npm run lint
in each workspace before committing and
npm run type-check
in
frontend
; there is no Prettier config, so mirror surrounding formatting.
The API relies on Jest (
npm run test
inside
backend
), enforcing 70% global coverage via
backend/jest.config.js
. Keep unit cases under
backend/tests/**
, API suites under
backend/api/tests/**
, and use
npm run test:integration:jest
for route workflows. The storefront uses Vitest:
npm test
for fast runs and
npm run test:coverage
for reporting. Run
test-integration.sh
before opening PRs that touch multiple surfaces.
Recent history pairs Conventional Commit verbs with optional emoji tags (
feat:
,
fix:
,
docs:
plus 🚀 or 🎯). Keep subjects imperative, under ~60 characters, note the rationale, and reference issues when available. PRs should summarise changes, list tests, flag migrations/env vars/Docker updates, and stay draft until linting, tests, and DB scripts pass locally.
Use
env.production.example
as the template for local
.env
files and keep credentials out of version control. SQLite dumps in
backend/data/
and uploads in
uploads/
may contain customer content, so do not share them externally. When adjusting deployment assets, rely on the
deploy-*.sh
helpers and update the matching
docker-compose.*.yml
so environments stay aligned.