diff --git a/PROJECT_FILES_GUIDE.md b/PROJECT_FILES_GUIDE.md index ba2c110..61e758f 100644 --- a/PROJECT_FILES_GUIDE.md +++ b/PROJECT_FILES_GUIDE.md @@ -1,676 +1,304 @@ # Project Files Guide -This document explains the role of the main files in this project in a way that should be easy to follow for a junior developer. +A junior-friendly walk-through of every folder and file that matters in this +repository. Read it alongside [README.md](README.md): the README tells you how +to run the project, this guide tells you where things live once it is running. -The project is split into a few clear parts: -- server code in [src/app.js](src/app.js) and the rest of [src](src) -- browser frontend files in [public](public) -- database structure and example data in [sql](sql) -- environment and local development helpers in the root folder and [scripts](scripts) +## How the application is organised -## How The Application Works At A High Level +There are three parts: -The project has two big sides: -- the backend, which provides templates, lookups, configuration, report storage, and audit logging through REST API endpoints -- the frontend, which runs in the browser, stores drafts locally, and uses the backend for centrally managed configuration and report submission +1. **Backend** — Node.js + Express in [src/](src/). Talks to MariaDB, serves + the API under `/api/v1/`, and serves the static frontend files. +2. **Frontend** — two single-page shells in [public/](public/): `user.html` for + operators and `admin.html` for administrators. Both are ES-module based + (no bundler) and use Bootstrap 5. +3. **Database** — MariaDB. Schema and seed data are in [sql/](sql/). Docker + loads them automatically on a fresh volume. -In simple terms: -1. Express starts the server. -2. The server exposes API endpoints under `/api/v1/...`. -3. The server also serves the frontend files from the [public](public) folder. -4. The browser loads the frontend entry point [public/app.js](public/app.js) which imports modules from [public/js/](public/js). -5. The frontend downloads templates and config from the API using a single batch request. -6. The frontend stores reports and images locally in IndexedDB. -7. Reports can be submitted to the server via `POST /api/v1/reports`. +### End-to-end request flow (simplified) -## Root Files +1. `docker compose up` starts three containers: `app`, `db`, `phpmyadmin`. +2. [src/server.js](src/server.js) boots Express and connects to MariaDB. +3. The browser loads `/` → `portal.html` (chooser page). +4. The user clicks a link and goes to `/login-admin` or `/login-user`. +5. After login, `/admin` or `/user` is served — both require a valid + `auth_token` cookie (see [src/middleware/authMiddleware.js](src/middleware/authMiddleware.js)). +6. The frontend shell loads either `admin-app.js` or `user-app.js`, which + hands off to `public/js/admin.js` or `public/js/user.js`. +7. The frontend calls `/api/v1/admin/all` to bulk-load every entity needed + for rendering, and keeps working drafts in IndexedDB. + +## Root files ### [package.json](package.json) -Role: -Defines the Node.js project itself. - -What it contains: -- project name and version -- npm scripts such as `start`, `dev`, and `test:environment` -- dependency list such as `express`, `mariadb`, and `dotenv` - -Why it matters: -When you run `npm install` or `npm start`, Node uses this file to know how the project should behave. - -### [README.md](README.md) - -Role: -Main entry document for developers. - -What it contains: -- project purpose -- setup steps -- available endpoints -- development notes - -Why it matters: -This is the first file a new developer should read before touching the code. +Defines the Node project: scripts (`start`, `dev`, `test:environment`), +dependencies (Express, MariaDB driver, cookie-parser, cors, dotenv), and the +minimum Node version. ### [docker-compose.yml](docker-compose.yml) -Role: -Starts the full local development environment. - -What it contains: -- the application container -- the MariaDB container -- the phpMyAdmin container -- port mappings and volume configuration - -Why it matters: -Instead of installing and configuring everything manually, you can start the full stack with one command. - -### [.env.example](.env.example) - -Role: -Example environment configuration. - -What it contains: -- default port values -- database host, name, user, and password placeholders - -Why it matters: -It shows which environment variables the application expects. - -### [.env](.env) - -Role: -Real environment file used on the current machine. - -What it contains: -- actual local values for ports and database credentials - -Why it matters: -The backend reads this file during startup through `dotenv`. - -## Public Folder - -The [public](public) folder contains files that are sent directly to the browser. - -### [public/user.html](public/user.html) - -Role: -Operator workspace HTML shell. - -What it contains: -- shared sidebar with template selector, sync button, report list, and search/filter -- report editor main area with hero, summary cards, form, inspector panel -- report list item `