# Dev setup — gigafibre-fsm

Quick reference for getting the stack running on a new machine.

## 1. Clone

```bash
git clone https://git.targo.ca/louis/gigafibre-fsm.git
cd gigafibre-fsm
```

## 2. Env files

The actual `.env` files are gitignored (they hold secrets). Each component
ships a `.env.example` with placeholder values + comments. Copy and fill in:

```bash
cp apps/ops/.env.example          apps/ops/.env
cp services/targo-hub/.env.example services/targo-hub/.env
```

Ask the team for the real values (or copy from `/opt/<service>/.env` on the
prod box if you have access). The hub `.env` is the long one — most fields
correspond to one external integration (Stripe, Twilio, Authentik, etc.).
Anything left blank disables that feature gracefully.

## 3. Run the apps

### `apps/ops` (Vue 3 + Quasar SPA)

```bash
cd apps/ops
npm install
npx quasar dev          # dev server at http://localhost:9000
npx quasar build        # production bundle in dist/spa/
```

Notes:
- The SPA expects to find ERPNext at the same origin in production
  (`erp.gigafibre.ca/ops/` is served from `/opt/ops-app/` via the
  ERPNext nginx). In dev, set `VITE_HUB_URL` to the local hub or the
  prod hub for backend calls.
- Authentik SSO redirects only work behind a real domain — dev mode
  uses the API token (`VITE_ERP_TOKEN`) for direct ERPNext calls.

### `services/targo-hub` (Node 20+)

```bash
cd services/targo-hub
npm install --production
node server.js          # listens on :3300
```

In production this runs in a Docker container under `/opt/targo-hub/` with
the host's `.env` file mounted.

### Other services

The `services/` and `apps/` directories also contain Docker compose stacks
that run on the prod server (ERPNext, Authentik, Traccar proxy, Fonoster,
DocuSeal, …). Reproducing them locally is rarely needed — the hub talks
to ERPNext + Authentik over the network and that's enough for most
front-end work.

## 4. Common tasks

| Task | Command |
| --- | --- |
| Build + deploy ops SPA to prod | `cd apps/ops && npx quasar build && scp -r dist/spa/* root@96.125.196.67:/opt/ops-app/` |
| Push hub code change | `scp services/targo-hub/lib/<file>.js root@96.125.196.67:/opt/targo-hub/lib/` then `ssh root@... 'docker restart targo-hub'` |
| Tail prod logs | `ssh root@96.125.196.67 'docker logs -f targo-hub --tail 50'` |
| Re-build after changing daemon.json or compose | `docker compose up -d --force-recreate` from the relevant `/opt/<service>/` |

## 5. Where things live

```
apps/ops/                   Quasar SPA — main internal tool (dispatch, clients, …)
apps/ops/src/pages/         Top-level pages (DispatchPage, ClientDetailPage, …)
apps/ops/src/composables/   Shared logic (useMap, useResourceFilter, …)
apps/ops/src/components/shared/detail-sections/   Per-doctype detail panels
services/targo-hub/         Node middleware between SPA / ERPNext / 3rd parties
services/targo-hub/lib/     One module per integration (auth, dispatch, ai, …)
services/targo-hub/server.js Top-level HTTP router
docs/                       This file + future runbooks
```

## 6. Auth quirks (fyi)

- **Authentik staff instance** = `auth.targo.ca` (admin token in
  `AUTHENTIK_TOKEN`). ERPNext uses it as an OAuth provider.
- **Authentik client instance** = `id.gigafibre.ca` (separate stack,
  for customer portal — uses `/opt/authentik-client/`).
- Inviting a user via ops Settings → Utilisateurs hits
  `POST /auth/users` on the hub, which (a) creates the Authentik user,
  (b) sets a temp password, (c) emails it via Mailjet, (d) creates the
  matching ERPNext System User.
- The Authentik recovery email flow isn't configured (no `flow_recovery`
  on the brand) — the hub sends the credentials itself instead.