---
phase: screens
kind: level
level: home
---

# Level — Home pages (SmartAppHome / SmartModuleHome / SmartSectionHome)

Use this level whenever a menu node needs an **explicit landing page** — the
first thing the user sees when they click an application, a module or a section
in the navigation. A home page is **not** a free-form analytics dashboard (that
is `SmartDashboard`); it is a launchpad combining a few KPIs with quickLinks to
the next level of the hierarchy.

## Where the home screen is written

A home page sits **above** the section level, so it has no section folder of its
own. Write it in the `screen.md` of the **landing section** of the module/app
(or a dedicated `*-home` section if the menu has one), and state its scope in
the heading. The module/app-level `screen.md` stays a one-line rollup pointer.

## When to use

| Type               | Trigger                                                                 |
|--------------------|-------------------------------------------------------------------------|
| `SmartAppHome`     | The application has ≥2 modules. One per app. (1 module = skip)           |
| `SmartModuleHome`  | The module has ≥2 sections. One per such module. (1 section = skip)      |
| `SmartSectionHome` | The section hosts SIBLING RESOURCES (≥2) with no section-level screen — MANDATORY there (SCR-020, err) — or is explicitly a launchpad/overview (`*-home`, `*-overview`). A section whose own `SmartListView` is the entry point needs none. |

The deep audit flags missing home pages: SCR-006 (apps with ≥2 modules but no
`SmartAppHome`), SCR-007 (modules with ≥2 sections but no `SmartModuleHome`),
SCR-020 (multi-resource sections with no `SmartSectionHome` — err, see below).

## What to produce

Every home screen carries two things:

1. **Widgets** — small KPI / counter / chart cards at the top (same vocabulary
   as `SmartDashboard`, see `levels/dashboard-screens.md`).
2. **QuickLinks** — the ordered navigation cards below the widgets, each pointing
   to a child screen.

The home page is where you wire navigation explicitly — app home → module home →
section home → list page — mirroring the route hierarchy `scaffold-routes`
generates.

### `SmartAppHome` — application landing page

```markdown
### SCR-CRM-HOME-001 — CRM (SmartAppHome)
- **Entité** : — (chaque widget porte la sienne)
- **Permission** : `crm.access`
- **Cas d'usage liés** : UC-CRM-HOME-001
- **Widgets** :
  - open-deals — Affaires ouvertes (kpi, Opportunity, count, `status=open`, col 3)
  - won-amount — Montant signé YTD (kpi, Opportunity, sum, `amount;status=won`, col 3)
  - active-clients — Clients actifs (counter, Client, count, `status=active`, col 3)
  - open-claims — Litiges en cours (counter, Claim, count, `status!=closed`, col 3)
- **QuickLinks** :
  - Prospects (icon users) → SCR-CRM-PROSPECTS-HOME-001
  - Clients (icon building) → SCR-CRM-CLIENTS-HOME-001
  - Facturation (icon file-invoice) → SCR-CRM-BILLING-HOME-001
```

Notes:
- No module/section segment in the code — `SmartAppHome` sits above the module
  level. Write it in the app's landing-section `screen.md`.
- The screen-level entity is optional; each widget declares its own.
- QuickLinks typically point to a `SmartModuleHome`. For a single-module app,
  point directly to the first list page of that module.

### `SmartModuleHome` — module landing page

```markdown
### SCR-CRM-CLIENTS-HOME-001 — Clients (SmartModuleHome)
- **Entité** : — (chaque widget porte la sienne)
- **Permission** : `crm.clients.read`
- **Cas d'usage liés** : UC-CRM-CLIENTS-HOME-001
- **Widgets** :
  - total — Clients (kpi, Client, count, col 3)
  - new30 — Nouveaux 30j (counter, Client, count, `createdAt>=30d`, col 3)
  - by-cat — Par catégorie (chart-pie, Client, `category.name`, col 6)
- **QuickLinks** :
  - Annuaire clients (icon list) → SCR-CRM-CLIENTS-LIST-001
  - Segmentation (icon tag) → SCR-CRM-SEGMENTS-LIST-001
  - Litiges & réclamations (icon alert) → SCR-CRM-CLAIMS-LIST-001
```

Notes:
- A module code is present, no section segment. Write it in the module's
  landing-section `screen.md`.
- QuickLinks typically point to a `SmartSectionHome` or directly to a
  `SmartListView`/`SmartDashboard` of a section.

### `SmartSectionHome` — section landing page

MANDATORY for every section hosting sibling resources with no section-level
screen (SCR-020, err — the seeded menu entry must mount a page), and for
explicit overview/launchpad sections. For sections whose own list IS the entry
point, the `SmartListView` serves as the landing page (`scaffold-routes`
already maps `app.module.section` to the list) — no home needed.

```markdown
### SCR-HR-EMPLOYEES-HOME-001 — Employés (SmartSectionHome)
- **Entité** : — (chaque widget porte la sienne)
- **Permission** : `hr.employees.read`
- **Cas d'usage liés** : UC-HR-EMPLOYEES-HOME-001
- **Widgets** :
  - headcount — Effectif (kpi, Employee, count, col 3)
  - on-leave — En congé (counter, Employee, count, `status=onLeave`, col 3)
  - by-dept — Par département (chart-pie, Employee, `department.name`, col 6)
- **QuickLinks** :
  - Annuaire (icon users) → SCR-HR-EMPLOYEES-LIST-001
  - Contrats (icon file-text) → SCR-HR-CONTRACTS-LIST-001
  - Demandes de congés (icon calendar) → SCR-HR-LEAVE-LIST-001
```

## Widget vocabulary

Same shape as `SmartDashboard` widgets — `kpi | counter | chart-line | chart-bar
| chart-pie | list` (see `levels/dashboard-screens.md`). Home pages typically use
3-4 KPIs/counters at the top, optionally one chart, and **never more than one
list widget** (the quickLinks already serve as navigation).

## QuickLinks vocabulary

Each quickLink has a unique key, a button label (user language), an optional
Lucide `icon`, a navigation target (a screen `code` that exists in the tree),
and an optional permission gate (the link is hidden if the actor cannot access
the target). The exact config-as-data shape is in `references/smartcomponents.md`.

## Auto-generation rule

Walking the menu tree top-down, propose home pages eagerly and **before** their
child screens, so navigation targets stay valid:

1. **Application** with ≥2 modules → a `SmartAppHome` first, then each module.
2. **Module** with ≥2 sections → a `SmartModuleHome` after the app home, then
   each section.
3. **Section** hosting sibling resources (or explicit `*-home`/`*-overview`) →
   a `SmartSectionHome` before the list/form/kanban screens (SCR-020, err).

## Common mistakes

- **A module/section segment on `SmartAppHome`**, or a section segment on
  `SmartModuleHome` → these home types sit above that level.
- **Forgetting quickLinks** → the page shows KPIs only and the user cannot drill
  down (audit SCR-006/007 secondary check).
- **A quickLink target pointing to a missing screen** → fails SCR-008.
- **Using `SmartDashboard` instead of a home type** for a navigational landing
  page → no quickLinks grid is rendered. Use `SmartDashboard` only for free-form
  analytics.
- **Home pages for a single-module app or single-section module** → unnecessary
  noise; the list page already serves as the entry point.

> **SCR-020 (err)** — a section whose screens all attach to sibling RESOURCES
> (no section-level screen) MUST declare its `SmartSectionHome`: without it the
> seeded menu entry mounts nothing (blank screen) and the resources are
> reachable only by typed URL. Propose it by default for every multi-resource
> section — quickLinks, one per resource, permission = the section floor.