# Environment & Architecture (Dev / Prod, System / Apps)

This document defines how dev and prod environments are structured, how system and apps relate, and how `.env` files are used.

## 1. Environments

We maintain at least two environments:

- Dev: local development tree (e.g. `/Users/rbutare/dev`).
- Prod: production tree on a remote server or separate filesystem (e.g. `/home/intel145/websites` or similar).

Dev and prod:

- Live on different servers or filesystems.
- Have their own `.env` files and path layouts.
- Share architecture concepts (system + apps) but not necessarily identical paths.

## 2. Two-tier architecture: system and apps

Top-level dev layout (example):

```text
dev
|-- apps
|   |-- defapp
|   |   |-- admin
|   |   |-- audit
|   |   |-- data
|   |   |   |-- config
|   |   |   |-- logs
|   |   |   `-- tmp
|   |   |-- js
|   |   |-- pages
|   |   |-- php
|   |   |-- sql
|   |   `-- tools
|   |-- fid
|   |-- games
|   |-- tips
|   |   (same substructure as defapp)
|   |-- tmp
|   `-- tools
|-- repos
|-- system
|   |-- admin
|   |-- audit
|   |-- data
|   |   |-- config
|   |   |-- logs
|   |   `-- tmp
|   |-- js
|   |-- pages
|   |-- php
|   |-- sql
|   `-- tools
`-- templates
    `-- sys
        `-- pages
```

Key ideas:

- `system/` holds shared framework code and data (admin, audit, js, pages, php, sql, tools).
- `apps/` holds per-app trees; each app (e.g. `defapp`, `fid`, `tips`) mirrors the system layout for consistency.
- `templates/` holds reusable system templates (e.g. base pages).

## 3. App naming and location

- An app called `defapp` lives under `apps/defapp`.
- Example paths in dev:

  - `APP_NAME=defapp`
  - `APP_ROOT=/Users/rbutare/dev/apps/defapp`

Other apps follow the same pattern:

- `apps/fid`
- `apps/tips`
- `apps/games` (with its own substructure as needed).

## 4. System-level `.env`

The system-level `.env` file lives at the dev root:

```text
/Users/rbutare/dev/.env
```

It defines (example):

```env
# System-level configuration for scaffolding and paths

ROOT=/Users/rbutare/dev
SYSTEM_ROOT=/Users/rbutare/dev/system

# Projects/apps root (new apps created here)
PROJECT_ROOT=/Users/rbutare/dev/apps

# Deploy root (prod apps mirror location concept)
DEPLOY_ROOT=/Users/rbutare/dev/prod

DEFAULT_APP_VERSION=v1.0.0
BASE_URL_PREFIX=https://apps.intellihometech.com/tmp/v1/

# Example DB settings (dev)
DB_CHARSET=utf8mb4
DB_HOST=localhost
DB_NAME=intel145_fidDev
DB_USER=intel145_drumhill
DB_PASS=***redacted***
```

Rules:

- `ROOT` is the base root of the dev environment.
- `SYSTEM_ROOT` points to the system tree (`dev/system`).
- `PROJECT_ROOT` points to the apps root (`dev/apps`), not a specific app folder.
- `DEPLOY_ROOT` is a local mirror location for production apps if needed.

Prod will have its own `.env` in its root with analogous variables but different values and paths.

## 5. App-level `.env`

Each app has its own `.env` file at:

```text
/Users/rbutare/dev/apps/<appName>/.env
```

Seeded from `env.example` by scaffold scripts, then customized.

Example for `defapp`:

```env
APP_NAME=defapp
APP_VERSION=v1.0.0

BASE_URL=https://apps.intellihometech.com/tmp/v1/defapp/

ROOT=/Users/rbutare/dev
SYSTEM_ROOT=/Users/rbutare/dev/system
PROJECT_ROOT=/Users/rbutare/dev/apps
APP_ROOT=/Users/rbutare/dev/apps/defapp
DEPLOY_ROOT=/Users/rbutare/dev/prod

DB_SERVER_ID=
DB_HOST=localhost
DB_CHARSET=utf8mb4
DB_NAME=intel145_fidDev
DB_USER=intel145_drumhill
DB_PASS=***redacted***

DEBUG=1

# Optional keys per app
# OPENAI_KEY=
# SMTP_HOST=
# SMTP_USER=
# SMTP_PASS=
# STRIPE_KEY=
```

App `.env`:

- Inherits structure from system `.env`.
- Overrides app-specific fields: `APP_NAME`, `APP_ROOT`, `BASE_URL`, DB values if needed.
- Is the primary source of configuration for app code and scripts.

## 6. Config loading rules

- System tools (installer, newapp.sh, audits):

  - Read `/Users/rbutare/dev/.env` (or the prod equivalent) via a shared loader script.
  - Use `ROOT`, `SYSTEM_ROOT`, `PROJECT_ROOT`, `DEPLOY_ROOT` to generate app folders and defaults.

- App code and scripts:

  - Read the app-level `.env` in `apps/<appName>/.env`.
  - Never hardcode paths or credentials; always resolve from `.env`.
  - May reference system `.env` if needed, but prefer app `.env` as primary.