# Angular Structure Standard

Use this standard for Angular implementation chunks.

## Source Guidance

This project follows current Angular standalone-component architecture and the
official Angular style-guide direction: keep related component files together,
keep components focused on presentation, and move reusable or decoupled logic
out of components.

Before Angular, PrimeNG-style UI, RxJS, or Apollo Angular implementation work, consult
the local pinned references in `ai/references/frontend-frameworks/` and the
usage rules in `ai/references/framework-reference-policy.md`. Browse official
docs only when the pinned reference is missing, stale for the installed version,
or the chunk explicitly asks for current/latest documentation.

## Component Structure

- Standalone components are architectural/provider-based Angular components; they are not "single-file components".
- Large components must not use giant inline templates or styles.
- Non-trivial pages, panels, shells, forms, dialogs, admin views, and feature workflows should use separate `.ts`, `.html`, `.scss`, and nearby `.spec.ts` files when behavior is significant.
- Organize first by feature/domain. Within a feature directory, use predictable subdirectories such as `components/`, `services/`, `pages/` or `views/`, and `models/` or `types/` when the feature has enough files to justify them.
- Feature-local UI components should live under feature-local `components/` directories when the feature has more than one component or the directory would otherwise mix components, services, and types.
- Feature-local services should live under feature-local `services/` directories.
- Shared singleton services may live under established `core/<domain>/` directories when they are intentionally app-wide.
- Shared reusable UI primitives should live in a clear shared UI component area such as `ui/components/`; shared directives should live in a clear directive area such as `ui/directives/`.
- Small primitive components may use inline template/style only when genuinely tiny and readable.
- Root `app` files must stay thin and delegate feature UI/state to focused components and services.
- `index.html` must remain the Angular document shell only. Do not put product UI there.
- Component logic belongs in the owning component `.ts`.
- Component-specific styles belong in the owning component `.scss`.
- Global styles should remain minimal: Tailwind entry, theme tokens, resets, and true app-wide rules only.
- Feature UI must be broken into focused components when the template or state grows beyond a small readable unit.
- Avoid artificial splitting that hides simple local behavior or creates unreadable indirection.
- Do not create type-only folders mechanically for tiny one-file features; use subdirectories when they improve navigation and ownership.

## State And Services

Canonical UI data-flow and view-model boundary rules live in
`ai/standards/angular-ui-data-flow.md`. Apply that standard whenever an Angular
chunk touches semantic UI state, Runtime Action Center surfaces, app-shell state,
GraphQL data, socket invalidation, or reusable UI components.

- Shared singleton behavior belongs in injectable services.
- Feature-specific state belongs close to the feature unless intentionally shared.
- Auth/current-user state, theme state, remote/dev-console state, and reusable API orchestration should live in services when used by multiple components.
- Components should coordinate view behavior and delegate durable/shared behavior to services.
- Use Angular signals for local or feature UI state and `computed()` for
  derived view models. Templates should read signal-backed state normally and
  let Angular update the view; implementation must not append, patch, or query
  DOM nodes as the source of application state.
- Collapsed/expanded UI state is presentation only. It must not prevent
  underlying service or signal state from updating, and expanding a collapsed
  view should render the latest already-applied state.
- Avoid expensive template method calls that rebuild non-trivial view models on
  every change-detection pass. Prefer a component/service signal or computed
  view model fed by canonical service state.
- Use `effect()` for imperative side effects only, not for deriving view state
  that can be expressed with `computed()`.

## GraphQL

- Use generated Apollo Angular services from `apps/frontend/src/app/core/graphql/generated`.
- Put GraphQL operation documents under `apps/frontend/src/app/core/graphql/operations`.
- Do not hand-write GraphQL types that should come from GraphQL Code Generator.

## UI Foundation

- For visible frontend UI changes, apply `ai/standards/ui-review.md`.
- Preserve the existing Angular/Tailwind/internal-UI-component architecture.
- Do not add Angular Material. Do not assume PrimeNG is installed; PrimeNG docs
  are a design/reference benchmark unless a future requirements/planning pass
  explicitly adds the dependency.
- Shared reusable UI primitives should be built first in `ui/components/` when a
  pattern is expected to recur. Keep them theme-aware, accessible where
  practical, and visually benchmarked against the relevant reference.
- Use `@lucide/angular` for modern app icons where an icon exists. Do not
  hand-roll icons unless no suitable library icon exists or the asset is a
  deliberate brand/custom graphic.
- Keep local wrappers and primitives app-opinionated rather than raw framework
  examples.
- Preserve mobile-first stacked-view behavior unless a reviewed design change explicitly replaces it.
- Lumen is the bright default admin/auth theme and should carry a distinct Laravel/WorkOS-inspired product feel, not merely a token rename of Classic.
- Classic should preserve the compatibility/current visual direction and remain visibly distinct from Lumen.
- Lumen forms use underline-style inputs with clear focus/error states; boxed inputs belong to Classic compatibility or explicit component needs.
- Role-aware admin navigation should use a polished Admin dropdown for admin-only destinations such as Users and Dev Console. Standard users must not see admin controls.
- The landing page should remain a useful UI foundation showcase while this product is establishing components and themes.
- Remote Dev Operator Console UI should present a terminal-like output panel plus prompt/input shell, clearly labeling wired behavior versus placeholders.