chore(markdown): Adding main README and docs/software_requirements_specification.md

README.md

@@ -0,0 +1,131 @@
+# GoETAAPI
+
+This repository contains the backend API and database layer for **ETA Viaporte** — a logistics marketplace platform.
+
+> The project is currently at the **database design and infrastructure** stage. The sections below describe what is available and how to work with it.
+
+---
+
+## Repository Structure
+
+```
+GoETAAPI/
+├── app/              # Go API source (in progress)
+└── db/
+    ├── Models/       # Schema design files (MySQL Workbench + SQL scripts)
+    ├── container/    # Dockerfile for the MariaDB test container
+    └── service/      # Docker Compose + Makefile for local deployment
+```
+
+---
+
+## DB
+
+### Schema Design
+
+The database schema is defined under `db/Models/` and targets the schema `u947463964_etaviaporte`.
+
+| File | Description |
+|---|---|
+| `db/Models/eta_rbac.mwb` | MySQL Workbench model — open this to visualize the full schema diagram |
+| `db/Models/schemas/eta_rbac.sql` | Forward-engineered SQL schema (generated from the `.mwb` model) |
+| `db/Models/init/eta_rbac_init.sql` | Seed / initialization data |
+| `db/Models/eta_rbac_requirements.md` | Human-readable data requirements derived from the schema constraints |
+
+To inspect or modify the schema visually, open `db/Models/eta_rbac.mwb` with **MySQL Workbench**.
+
+The schema covers:
+- **Users & Authentication** — `users`, `auth_identities`, `verification_tokens`, `sessions`
+- **RBAC** — `applications`, `roles`, `permissions`, `role_permissions`, `user_roles`
+- **Companies & Locations** — `companies`, `locations`
+- **Loads & Shipments** — `loads`, `vehicles`, `shipment_proposals`, `shipment_agreements`, `load_shipments`
+
+---
+
+### Docker Container
+
+The image is built from `db/container/Dockerfile`. It uses **Alpine + MariaDB** and automatically generates a root password on first run. SQL files placed in `/docker-entrypoint-initdb.d` inside the container are executed on startup.
+
+#### Build the image
+
+Run from `db/container/`:
+
+```sh
+docker buildx build -t eta/eta-db .
+```
+
+#### Run the container (basic)
+
+```sh
+docker run --name eta-db -d -p 3306:3306 eta/eta-db
+docker logs -f eta-db   # root password is printed here on first boot
+```
+
+#### Run the container with a named database and user
+
+```sh
+docker run --name eta-db \
+  -e MYSQL_DATABASE=u947463964_etaviaporte \
+  -e MYSQL_USER=etaapi \
+  -e MYSQL_PASSWORD="secret_password" \
+  -d -p 3306:3306 eta/eta-db
+```
+
+#### Run with schema initialization scripts
+
+Mount a directory of `.sql` files into `/docker-entrypoint-initdb.d` and they will be executed in order on first start:
+
+```sh
+docker run --name eta-db \
+  -e MYSQL_DATABASE=u947463964_etaviaporte \
+  -e MYSQL_USER=etaapi \
+  -e MYSQL_PASSWORD="secret_password" \
+  -v ./docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d \
+  -d -p 3306:3306 eta/eta-db
+```
+
+> **Note:** Avoid using `"` (double quotes) in SQL scripts — use `'` (single quotes) instead. Inline comments at the end of SQL statements may also cause parsing errors.
+
+---
+
+### Docker Compose (local testing)
+
+`db/service/compose.yml` deploys the `eta/eta-db` image with the schema and seed data pre-loaded. It mounts `db/service/initdb/` into the container's init directory.
+
+Before deploying with Compose, populate `db/service/initdb/` by running `make prepare` (see below), then start the service:
+
+```sh
+cd db/service
+docker compose up -d
+```
+
+The service exposes MariaDB on port `3306` with:
+
+| Variable | Value |
+|---|---|
+| `MYSQL_DATABASE` | `u947463964_etaviaporte` |
+| `MYSQL_USER` | `etaapi` |
+| `MYSQL_PASSWORD` | `secret_password` |
+
+> The `initdb/` volume uses the `:Z` SELinux label to avoid permission denied errors on SELinux-enabled systems.
+
+---
+
+### Makefile — Prepare init scripts
+
+The `db/service/Makefile` copies the latest schema and seed files from `db/Models/` into `db/service/initdb/`, so they are picked up by Docker Compose on the next container start.
+
+```sh
+cd db/service
+make prepare
+```
+
+This runs:
+1. Clears any existing `.sql` files from `db/service/initdb/`.
+2. Copies `db/Models/schemas/eta_rbac.sql` → `initdb/00-schema.sql`
+3. Copies `db/Models/init/eta_rbac_init.sql` → `initdb/01-initdb.sql`
+
+Always run `make prepare` after updating the schema model before bringing the Compose service up.
+
+
+