# defapp Architecture

## Overview

defapp is composed of a modular Bash-based CLI and a set of templates and manifest
files. It creates new apps using standardized structures and audits existing apps
for documentation and standards compliance.

## Components

### 1. CLI dispatcher (newapp.sh)

- Parses subcommands: init, audit, help.
- Loads configuration from:
  - /home/intel145/websites/.env (system).
  - /home/intel145/websites/apps/defapp.env (app).
- Delegates to module scripts for folder, customize, templates, docs, and audit.

### 2. Folder module

- Responsible for:
  - Resolving base paths using env vars (e.g., APPS_BASE=/home/intel145/websites/apps).
  - Creating directory structures for new apps:
    - <APP_DIR>/docs
    - <APP_DIR>/src
    - <APP_DIR>/tests
    - <APP_DIR>/scripts

### 3. Customize module

- Computes dynamic variables:
  - APP_NAME (from CLI arg).
  - APP_SLUG (derived from APP_NAME).
  - APP_DATE (current date).
  - APP_DESCRIPTION (CLI arg or default).
- Merges system/app config from .env files.

### 4. Templates module

- Reads manifest.json under templates/standards/newapp/<version>.
- Uses envsubst (and optional JSON tools) to:
  - Load variable definitions.
  - Iterate templates and render src → dest with variables injected.

### 5. Docs module

- Provides helper functions for:
  - Updating docs/INDEX.md links.
  - Checking presence/headings for audit mode.
  - Future tasks (e.g., auto-adding entries to PROJECT_LOG.md).

### 6. Audit engine

- Uses manifest.json "required" section to:
  - Check required files exist.
  - Check required headings are present via regex patterns.
- Outputs a compliance report usable in CLI and CI.

## Two-Tier Architecture Rules

### Tier 1: System

- The system tier represents shared configuration and global behavior for all apps
  under /home/intel145/websites.
- System configuration is stored in:
  - /home/intel145/websites/.env (global env).
- System responsibilities:
  - Define base paths (e.g., APPS_BASE=/home/intel145/websites/apps).
  - Define organization-level defaults (ORG_NAME, default license, logging conventions).
  - Define available standards packages and their locations (e.g., templates/standards/newapp/v1).

Rules:
- System config is loaded first for any CLI run.
- System tier MUST NOT contain app-specific secrets.
- Changes to system config SHOULD be documented in defapp/docs/PROJECT_LOG.md.

### Tier 2: Apps

- The apps tier represents individual applications (including defapp) under
  /home/intel145/websites/apps.
- App-specific configuration is stored in:
  - /home/intel145/websites/apps/<app>.env (per-app env).
- App responsibilities:
  - Provide app-specific overrides (e.g., APP_OWNER, APP_LICENSE).
  - Declare which standards package/version it follows.
  - Implement app-specific logic and documentation.

Rules:
- App config is loaded after system config; app values override system defaults.
- Each app MUST have a docs/ folder following the standards, unless explicitly exempt.
- Each app SHOULD track major config changes and standards updates in its own PROJECT_LOG.md.

### Interaction Between Tiers

- newapp.sh and defapp modules MUST:
  - First source /home/intel145/websites/.env if present.
  - Then source /home/intel145/websites/apps/<app>.env if present.
- Standards packages (templates/standards/...) live in the system tier but are applied to apps.
- The audit engine uses system-level standards definitions and evaluates app-level compliance.