---
name: catalyst-project-structure
description: >
  Provides structured knowledge about the Aurora Catalyst frontend architecture, folder hierarchy,
  and file placement rules. Enables AI to plan file locations and identify which files to modify for
  new features. Trigger: When navigating the codebase, asking "where is X", "where should I put X",
  planning a new feature, or creating new bounded contexts/modules.
license: MIT
metadata:
  author: aurora
  version: '1.0'
---

## When to Use

- User asks "where is..." or "where should I put..."
- Planning file locations for a new feature
- Creating a new bounded context or module
- Understanding which files to modify for a change
- Navigating between layers (layout, domains, bounded contexts, modules)

---

## Architecture Overview

Aurora Catalyst frontend follows a **Domain-Driven** architecture with three main layers:

| Layer         | Path               | Responsibility                                                 | Modify?                     |
| ------------- | ------------------ | -------------------------------------------------------------- | --------------------------- |
| **App Shell** | `src/app/`         | Bootstrap, root config, global routes                          | Rarely                      |
| **Domains**   | `src/app/domains/` | Feature domains, each with its own layout and bounded contexts | YES — primary work area     |
| **UI Lib**    | `libs/ui/`         | Spartan Helm components (auto-generated, local)                | NO — managed by Spartan CLI |

Each domain owns its layout. There is no shared `src/app/layout/` folder — layouts live inside their
domain.

---

## Project Structure

```
frontend/
├── libs/ui/                               # Spartan Helm UI Components (DO NOT MODIFY)
│   ├── [component]/src/index.ts           # 56+ components (sidebar, button, avatar, etc.)
│   └── ...                                # Managed via @spartan-ng/cli
│
├── src/
│   ├── app/
│   │   ├── app.ts                         # Root component (<router-outlet />)
│   │   ├── app.config.ts                  # Application providers
│   │   ├── app.routes.ts                  # Root routes (lazy-loads domains)
│   │   │
│   │   ├── core/                          # Singleton Services (future)
│   │   │   └── (auth, theming, etc.)
│   │   │
│   │   └── domains/                       # Feature Domains
│   │       ├── admin/                     # Admin domain
│   │       │   ├── layout/
│   │       │   │   ├── layout.component.ts       # Admin shell: sidebar + header + outlet
│   │       │   │   ├── site-header.ts            # Header with breadcrumbs + sidebar trigger
│   │       │   │   └── sidebar/
│   │       │   │       ├── app-sidebar.ts        # Sidebar shell (Spartan sidebar-inset)
│   │       │   │       ├── nav-main.ts           # Primary nav with collapsibles
│   │       │   │       ├── nav-projects.ts       # Projects section with dropdown menus
│   │       │   │       ├── nav-secondary.ts      # Secondary links (support, feedback)
│   │       │   │       ├── nav-user.ts           # User avatar + dropdown menu
│   │       │   │       └── sidebar-data.ts       # Nav interfaces + data configuration
│   │       │   ├── bounded-contexts/
│   │       │   │   ├── index.ts                  # Re-exports all navigations
│   │       │   │   └── [context-name]/           # See "Bounded Context Structure"
│   │       │   └── routes.ts                     # Admin routes (lazy-loads contexts)
│   │       │
│   │       └── auth/                      # Auth domain
│   │           ├── layout.ts              # Minimal layout (no sidebar)
│   │           ├── routes.ts
│   │           └── sign-in/
│   │               ├── sign-in.component.ts      # Two-column login page
│   │               └── login-form.ts             # Reactive login form
│   │
│   ├── styles.css                         # Global styles (Tailwind v4 + Spartan theme)
│   ├── main.ts                            # Bootstrap entry point
│   └── index.html                         # HTML host
│
├── angular.json                           # Angular workspace config
├── tsconfig.json                          # TS config with @spartan-ng/helm/* path aliases
└── components.json                        # Spartan CLI config (componentsPath: libs/ui)
```

---

## Bounded Context Structure

Each bounded context under `domains/admin/bounded-contexts/` follows this pattern:

```
[context-name]/
├── [context-name].navigation.ts           # Menu items for this context
├── [context-name].routes.ts               # Routes for all modules in context
└── [module-name]/
    ├── index.ts                           # Barrel exports
    ├── [module-name].columns-config.ts    # Grid column definitions
    ├── features/
    │   ├── [module-name]-list.component.ts    # List view
    │   └── [module-name]-detail.component.ts  # Detail/Create/Edit view
    └── data-access/
        ├── [module-name].graphql.ts       # GraphQL queries and mutations
        ├── [module-name].resolvers.ts     # Angular Router resolvers
        └── [module-name].service.ts       # Business logic + data operations
```

### File Responsibilities

| File                             | Purpose                                                           |
| -------------------------------- | ----------------------------------------------------------------- |
| `[context].navigation.ts`        | Exports `NavItem[]` consumed by the sidebar                       |
| `[context].routes.ts`            | Defines lazy-loaded routes for all modules in the context         |
| `[module].columns-config.ts`     | Column definitions for list/grid views                            |
| `features/*-list.component.ts`   | List page component (standalone, OnPush, default export)          |
| `features/*-detail.component.ts` | Create + Edit page component (standalone, OnPush, default export) |
| `data-access/*.graphql.ts`       | GraphQL query/mutation strings (overrideable by user)             |
| `data-access/*.resolvers.ts`     | Angular Router `ResolveFn` for pre-loading data                   |
| `data-access/*.service.ts`       | Injectable service with CRUD operations                           |
| `index.ts`                       | Re-exports public API of the module                               |

---

## Routing Architecture

```
app.routes.ts
└── loadChildren → domains/admin/routes.ts
    └── loadComponent → admin/layout/layout.component.ts (sidebar shell)
        └── children:
            └── path: 'iam' → loadChildren → iam/iam.routes.ts
                ├── path: 'users'     → users-list.component.ts
                └── path: 'users/:id' → users-detail.component.ts
```

### Key Patterns

- **Root routes** lazy-load entire domains
- **Domain routes** load the layout + lazy-load bounded contexts
- **Context routes** define module-level paths
- **All components** use `default export` for clean `loadComponent()` imports

---

## Decision Tree: Where to Put Code?

```
Adding a new business entity/module?
  → Create module folder under the appropriate bounded context
  → Follow the module structure (features/ + data-access/ + columns-config + index.ts)

Adding a new bounded context?
  → Create folder in domains/admin/bounded-contexts/[name]/
  → Add [name].navigation.ts and [name].routes.ts
  → Export navigation in bounded-contexts/index.ts
  → Add lazy route in domains/admin/routes.ts

Adding a new domain (e.g., public, customer portal)?
  → Create domains/[name]/ with layout/ and routes.ts
  → Add lazy route in app.routes.ts

Modifying the sidebar or header?
  → Edit files in layout/sidebar/ or layout/site-header.ts

Adding a reusable UI component?
  → If Spartan component: use @spartan-ng/cli to add to libs/ui/
  → If custom component: create in a shared/ folder (TBD)

Adding a new layout variant for admin?
  → Create new component in domains/admin/layout/
  → Reference it from domains/admin/routes.ts

Modifying grid columns for a module?
  → Edit [module].columns-config.ts

Customizing GraphQL queries?
  → Edit [module].graphql.ts in data-access/

Adding a new route to an existing context?
  → Edit [context].routes.ts

Modifying navigation menu for a context?
  → Edit [context].navigation.ts
```

---

## Component Conventions

| Convention         | Rule                                                |
| ------------------ | --------------------------------------------------- |
| Change detection   | Always `ChangeDetectionStrategy.OnPush`             |
| State              | Use `signal()`, `computed()`, `input()`, `output()` |
| Modules            | Standalone only — no `NgModule`                     |
| `standalone: true` | NEVER set explicitly (default in Angular 20+)       |
| Templates          | Inline for small, external for complex              |
| Exports            | `default export` for routed components              |
| Control flow       | `@if`, `@for`, `@switch` (native)                   |
| Injection          | `inject()` function, not constructor injection      |
| Forms              | Reactive forms only                                 |

---

## Path Aliases

| Alias                | Path                     | Usage                      |
| -------------------- | ------------------------ | -------------------------- |
| `@spartan-ng/helm/*` | `libs/ui/*/src/index.ts` | Spartan Helm UI components |

```typescript
import { HlmSidebarImports } from '@spartan-ng/helm/sidebar';
import { HlmButtonImports } from '@spartan-ng/helm/button';
```

---

## Quick Navigation Commands

```bash
# Find all files for a module
fd "users" src/app/domains/

# Find all components
fd ".component.ts$" src/app/

# Find all services
fd ".service.ts$" src/app/

# Find all route files
fd "routes.ts$" src/app/

# Find all navigation configs
fd ".navigation.ts$" src/app/

# Find column configurations
fd ".columns-config.ts$" src/app/

# Find GraphQL files
fd ".graphql.ts$" src/app/

# List bounded contexts
ls src/app/domains/admin/bounded-contexts/

# List Spartan UI components available
ls libs/ui/
```

---

## Adding a New Bounded Context — Step by Step

1. Create the folder structure:

   ```
   domains/admin/bounded-contexts/[name]/
   ├── [name].navigation.ts
   ├── [name].routes.ts
   └── [first-module]/
       ├── index.ts
       ├── [module].columns-config.ts
       ├── features/
       │   ├── [module]-list.component.ts
       │   └── [module]-detail.component.ts
       └── data-access/
           ├── [module].graphql.ts
           ├── [module].resolvers.ts
           └── [module].service.ts
   ```

2. Export navigation in `bounded-contexts/index.ts`:

   ```typescript
   export { newContextNavigation } from './[name]/[name].navigation';
   ```

3. Add lazy route in `domains/admin/routes.ts`:

   ```typescript
   {
     path: '[name]',
     loadChildren: () => import('./bounded-contexts/[name]/[name].routes').then(m => m.[name]Routes),
   }
   ```

4. Update sidebar data if needed (layout/sidebar/sidebar-data.ts)

---

## Resources

- **Spartan UI Components**: See `libs/ui/` — 56+ Helm components
- **Layout Components**: See `src/app/layout/`
- **Admin Domain**: See `src/app/domains/admin/`
- **Global Styles**: See `src/styles.css` (Tailwind v4 + Spartan theme)
