# Setting Up a New App with intelliTemplates

This guide describes how to create a new application using the intelliTemplates scaffolding tools and how to keep it aligned with system standards.

## Prerequisites

- intelliTemplates directory structure initialized.
- `setup/` scripts available and executable:
  - `setup/init_app.sh`
  - `setup/init_docs.sh`
  - `setup/check_app_conformance.sh`

Run this once to create system docs and common directories:

```bash
./setup/init_docs.sh system
```

## Step 1 – Create the App Skeleton

Create a new app named `myApp`:

```bash
./setup/init_app.sh myApp
```

This will:

- Copy `apps/defApp` if it exists, or create a minimal structure.
- Create required directories under `apps/myApp`:
  - `css/`, `css/themes/`, `docs/`, `templates/`, `php/`, `js/`, `partials/`, `data/`, `data/logs/`.
- Create or update:
  - `apps/myApp/includes.php`.
  - `apps/myApp/docs/README.md`.
  - `apps/myApp/docs/CONFIGURATION.md`.
  - `apps/myApp/docs/STANDARDS_DEVIATIONS.md`.

## Step 2 – Customize App Documentation

Edit the generated docs:

- `apps/myApp/docs/README.md`
  - Replace summary, dependencies, overrides.
  - Remove or update `STATUS: TEMPLATE` once ready.

- `apps/myApp/docs/CONFIGURATION.md`
  - Document app-specific JSON keys and DB-backed settings.
  - Confirm `__APP_NAME__` has been replaced.

- `apps/myApp/docs/STANDARDS_DEVIATIONS.md`
  - Set `Standards Version` to match `docs/STANDARDS.md`.
  - Add entries if you intentionally break or extend standards.

## Step 3 – Configure Templates and Layout

Configure which templates this app uses:

- `common/templates/`:
  - Contains shared layouts (e.g., `defaultLayout.php`).
- `apps/myApp/templates/`:
  - Add app-specific templates if needed.

In the app’s config (`apps/myApp/config.json` when created):

- Point `layout.template` to your default layout.
- Map sections such as `navBar`, `toolBar`, `navBarLeft`, `mainContent`, `footer` to the correct PHP files.

Example (conceptual):

```json
{
  "layout": {
    "template": "defaultLayout.php",
    "sections": {
      "navBar": "myAppNavBar.php",
      "mainContent": "myAppContent.php"
    }
  }
}
```

## Step 4 – Configure Defaults and Overrides

intelliTemplates uses separate files for configuration:

- System default config (shared):
  - `common/config.json` – base defaults for all apps.
- App config (overrides):
  - `apps/myApp/config.json` – app-specific overrides.

At runtime, the config loader:

1. Loads `common/config.json`.
2. Applies `apps/myApp/config.json`.
3. Applies database overrides from the `configuration` table (if enabled).
4. Optionally applies environment variables.

This keeps a clear default vs override boundary and makes it easier to reuse templates across apps [web:95][web:98].

## Step 5 – Run Conformance Checks

Use the conformance script to verify structure and syntax:

```bash
./setup/check_app_conformance.sh myApp
```

Or for all apps:

```bash
./setup/check_app_conformance.sh --all
```

The script will:

- Check required directories and docs.
- Check for template markers (`STATUS: TEMPLATE`, `TODO:`).
- Compare app standards version with system standards version.
- Run `php -l` on common and app PHP files (unless `--no-php-lint` is used).
- Write a summary to `logs/conformance.log` by default, unless `--log` is passed.

Errors cause a non-zero exit; warnings (including template markers and standards version mismatch) are reported in the summary.

---

## Future Work: PH4 Document (Outline)

Add this as `docs/PH4_FUTURE.md` or extend `PHASES.md` with a PH4 section:

```md
# Phase 4 – Future Enhancements

## Overview

Phase 4 focuses on advanced tooling and automation to enhance intelliTemplates beyond the initial standards and scaffolding.

## Planned Enhancements

- **Deeper static analysis**:
  - Integrate additional linters for PHP, JS, and CSS.
  - Expand checks beyond syntax (style and security-focused rules).

- **Config validation**:
  - Schema validation for `common/config.json` and `apps/appName/config.json`.
  - Automated checks for missing keys, invalid types, or conflicting settings.

- **Template registry**:
  - Central index of available templates and their usage by apps.
  - Tools to detect unused templates or conflicting overrides.

- **Migration tools**:
  - Scripts to assist in moving configuration from JSON files to database.
  - Versioned migrations with audit logs.

- **CI / scheduled checks**:
  - Integrate `check_app_conformance.sh` into CI pipelines.
  - Nightly or scheduled runs with consolidated reports.

## Tasks (Draft)

- Document config schema and validation rules.
- Implement JSON schema checks for system and app configs.
- Add template inventory and usage reporting tools.
- Add optional CI integration scripts.
```

---

## Next Steps for You (practical)

1. **Finalize the first template**:
   - Create `common/templates/defaultLayout.php`.
   - Wire it to use sections (`navBar`, `toolBar`, `navBarLeft`, `mainContent`, `footer`) based on config.
   - Ensure it reads config from:
     - `common/config.json` (defaults).
     - `apps/defApp/config.json` (for the golden app).

2. **Create the default config files**:
   - `common/config.json`:
     - Define default layout, sections, debug levels, and shared paths.
   - `apps/defApp/config.json`:
     - Minimal overrides (just enough to show how apps customize).

3. **Update `docs/CONFIGURATION.md`**:
   - Document the structure of `common/config.json` and `apps/appName/config.json`.
   - Show how the config loader merges them and applies database overrides.

4. **Update `docs/TEMPLATES.md` (optional new doc)**:
   - Describe:
     - The default template file(s).
     - How sections map to includes.
     - Where app-level overrides plug in.

5. **Run full cycle**:
   - `./setup/init_docs.sh system`
   - `./setup/init_app.sh defApp`
   - Build out `defApp` as the canonical template app.
   - `./setup/check_app_conformance.sh --all`
   - Iterate until defApp passes with no errors and only acceptable warnings.

This gives you a clean, documented path: new app setup, tooling, and a clear future roadmap, all aligned with your modular/template philosophy and with standard README/setup patterns [web:91][web:94][web:97].