# Standard App Structure — v2 (validated against real folder tree, piloted on `defapp`)

`defapp` was the old standard. This version corrects it against what's actually
in production across `register`, `aiwizard`, and `aicode`, and is being tested
by updating `defapp` itself before rolling out further.

## Mandatory per-app skeleton

```
{appname}/
├── {appname}.index.php    # entry point, dot-segment naming
├── public/                # web-servable root ONLY — everything else stays outside webroot
├── admin/                 # admin views/routes for this app
├── pages/                 # app pages/routes
├── templates/             # shared layout templates  (NOT "tmpl" — corrected from v1 draft)
├── config/
│   └── templates/         # config file templates
├── css/
│   └── themes/            # theme overrides (integrates with system-tier theme-manager)
├── js/
├── img/
├── php/                   # app-specific PHP includes/logic
├── data/
│   ├── config/
│   ├── fonts/
│   ├── logs/              # logs live HERE, not a top-level logs/ — corrected from v1 draft
│   └── sql/
├── docs/
│   ├── adr/               # architecture decision records (from aiwizard)
│   └── runbooks/          # from aiwizard
├── ai/
│   ├── prompts/
│   └── output/
├── audit/                 # app-specific audit checks (declared mandatory per app now)
├── tests/                 # NOT "test" — corrected from v1 draft
├── scripts/               # one-off/maintenance scripts for THIS app
├── tools/                 # maintained reusable CLI for THIS app
├── tmp/                   # scratch/ephemeral, gitignored
└── var/
    └── sessions/          # runtime state (PHP sessions, from register)
```

**Correction from v1:** `scripts/` and `tools/` are mandatory per-app (not
system-only as originally proposed) — real apps already keep app-specific
scripts/tools alongside system-wide ones. Both tiers get both folders; the
placement rule (below) decides which specific file goes where.

**Optional:** `src/{Controllers,Helpers,Parser}/` (or app-specific namespaces
like `aicode`'s `Database/Diagnostics/Logging/Models`) — only for apps that use
OOP/namespaced classes rather than the procedural style. Not every app needs this.

## Optional declared extension zones (per app, audited only if declared)

```
{appname}/
├── api/        # REST API layer (family-tree)
├── python/     # non-PHP runtime — venv itself is gitignored, never committed
├── assets/     # uploads, photos, exports (family-tree)
└── themes/     # only if beyond the standard css/themes/ override
```

## System tier — same mandatory-skeleton logic, system-wide scope

```
system/
├── .env                # golden rule: single source of truth for system-wide config
├── config/
├── data/
│   └── project.registry.json
├── logs/
├── audit/              # cross-app compliance checks — mandatory at this tier
├── tests/              # tests the shared tooling itself — mandatory at this tier
├── tools/
│   └── theme-manager/  # shared across apps — moved here, not a peer app
├── scripts/
├── docs/
└── php/
    └── aicode/         # shared library code — moved here, not a peer app
```

## The single placement rule (unchanged, still the test for every file)

> If a folder's contents apply to more than one app, or govern the tooling
> system itself, it belongs under `system/`, declared as a system extension.
> If a folder's contents are specific to one app's own behavior or
> requirements, it belongs under that app, declared as an app extension.

## Open item — not yet resolved by the tree alone

Where the app-level `.env` actually lives is unclear from directory names
alone (hidden files don't show in a tree listing). Confirm before the pilot:
does each app have its own `.env` under `config/`, or do all apps read only
from the system-tier `.env`? This decides whether "golden rule" is one file
or one-per-app.

## Pilot: what changes in `defapp` to test this

`defapp` currently has: `admin, ai/{output,prompts}, audit, config, css/themes,
data/{config,fonts,logs,sql}, docs, img, js, pages, php, scripts, sql, src/
{Controllers,Helpers,Parser}, templates, tests, tmp, tools`.

To bring it in line with v2, add:
- [ ] `public/` — carve out the actual web-servable files from wherever they
      currently sit (likely `pages/` or app root); everything else stays private
- [ ] `var/sessions/` — if defapp handles its own sessions rather than a shared
      mechanism
- [ ] `docs/adr/` and `docs/runbooks/` — currently `docs/` is flat
- [ ] `config/templates/` — currently `config/` is flat
- [ ] Resolve the redundant `sql/` vs `data/sql/` — pick one (recommend
      `data/sql/` only, drop the top-level `sql/`)
- [ ] Decide whether `src/` (OOP) or `php/` (procedural) is defapp's actual
      pattern — right now it has both, which suggests a style that hasn't
      fully committed either way

Nothing here needs `api/`, `python/`, or `assets/` — defapp has no declared
extensions, which is correct for a default/reference app.