Skip to content

Commit 556285b

Browse files
JrPribsJrPribs
committed
Updates coding standards and adds GitHub Actions.
1 parent 3333210 commit 556285b

7 files changed

Lines changed: 229 additions & 7 deletions

File tree

‎.github/workflows/firebase-hosting-merge.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# This file was auto-generated by the Firebase CLI
2+
# https://github.com/firebase/firebase-tools
3+
4+
name: Deploy to Firebase Hosting on merge
5+
on:
6+
push:
7+
branches:
8+
- main
9+
jobs:
10+
build_and_deploy:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
- run: npm ci && npm run build
15+
- uses: FirebaseExtended/action-hosting-deploy@v0
16+
with:
17+
repoToken: ${{ secrets.GITHUB_TOKEN }}
18+
firebaseServiceAccount: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_WHYTV_47175 }}
19+
channelId: live
20+
projectId: whytv-47175

‎.github/workflows/firebase-hosting-pull-request.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# This file was auto-generated by the Firebase CLI
2+
# https://github.com/firebase/firebase-tools
3+
4+
name: Deploy to Firebase Hosting on PR
5+
on: pull_request
6+
permissions:
7+
checks: write
8+
contents: read
9+
pull-requests: write
10+
jobs:
11+
build_and_preview:
12+
if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
- run: npm ci && npm run build
17+
- uses: FirebaseExtended/action-hosting-deploy@v0
18+
with:
19+
repoToken: ${{ secrets.GITHUB_TOKEN }}
20+
firebaseServiceAccount: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_WHYTV_47175 }}
21+
projectId: whytv-47175

‎CODING_STANDARDS/angular-cheat-sheet.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,13 @@
2424

2525
## 📥 State Management
2626

27-
- **CS-S01**: One-way flow: Component → Service → Store → Component → [§One-Way Data Flow]
28-
- **CS-S02**: Read state via store signals only → [§Signal Stores]
29-
- **CS-S03**: Update state via service methods only → [§Service Responsibilities]
27+
- **CS-S01**: One-way flow: Component → Service → Store → Component → [§State Architecture]
28+
- **CS-S02**: Read state via store signals only → [§Read Operations]
29+
- **CS-S03**: Update state via service methods only → [§Write Operations]
3030
- **CS-S04**: Use @ngrx/signals for shared state → [§Signal Stores]
3131
- **CS-S05**: No HTTP calls in stores → [§Signal Stores]
32+
- **📊 Decision Guide**: Where does X belong? → [State Architecture: Decision Guidelines]
33+
- **⚠️ Anti-patterns**: What NOT to do → [State Architecture: Anti-patterns]
3234

3335
## 🔧 Services
3436

‎CODING_STANDARDS/angular-state-architecture.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Angular State Architecture and Data Flow
2+
3+
> This document provides detailed architectural guidance for state management. For quick reference, see the [Angular Cheat Sheet](./angular-cheat-sheet.md). For implementation rules, see [Angular Coding Standards](./angular_coding_standards.md).
4+
5+
## Overview
6+
7+
This document outlines our application's state management architecture and the recommended data flow patterns. Following these patterns ensures consistent, maintainable, and predictable state management across the application.
8+
9+
## Architecture Layers
10+
11+
Our application state architecture consists of three primary layers:
12+
13+
1. **Global State Layer** - Central, shared application state
14+
2. **Service Layer** - Business logic and state mutation
15+
3. **Component Layer** - UI components with local state
16+
17+
## Data Flow Pattern
18+
19+
[CS-S01] Our application follows a bi-directional data flow pattern:
20+
21+
```
22+
READ (Direct)
23+
┌─────────────────────────┐
24+
│ │
25+
▼ │
26+
┌───────────────────┐ ┌───────────────────┐
27+
│ │ │ │
28+
│ Components │ │ Global State │
29+
│ (Consumers) │ │ (Storage) │
30+
│ │ │ │
31+
└───────────────────┘ └───────────────────┘
32+
│ ▲
33+
▼ │
34+
┌───────────────────┐ │
35+
│ │ │
36+
│ Services │────────────────┘
37+
│ │
38+
└───────────────────┘
39+
Services handle:
40+
- Business Logic
41+
- API Calls
42+
- Validation
43+
- State Updates
44+
45+
```
46+
47+
### Read Operations (State to Component)
48+
49+
[CS-S02] Components read data directly from the Global State Layer via Store Signals:
50+
51+
1. Global store signals expose reactive state to components
52+
2. Components subscribe to relevant store signals
53+
3. Components can derive local computed signals from store signals
54+
4. UI automatically updates when signal values change
55+
56+
### Write Operations (Component to State)
57+
58+
[CS-S03] Components write data to the Global State through Services:
59+
60+
1. Component dispatches an action by calling a service method
61+
2. Service performs business logic and validation
62+
3. Service updates the global state
63+
4. State changes propagate back to components via signals
64+
65+
## Responsibilities by Layer
66+
67+
### Global State Layer
68+
69+
**Store:**
70+
- Maintains the single source of truth for application state
71+
- Holds structured data models
72+
- Provides methods for state mutations [CS-S03]
73+
74+
**Store Signals:**
75+
- Exposes reactive state via signals [CS-S02]
76+
- Provides derived/computed state
77+
- Enables fine-grained reactivity
78+
79+
### Service Layer
80+
81+
**Services:**
82+
- Implement most domain business logic [CS-V03]
83+
- Handle data fetching and API communication [CS-S05]
84+
- Process and validate data before state updates
85+
- Orchestrate complex workflows
86+
- Manage side effects (e.g., logging, analytics)
87+
- Update global state [CS-S03]
88+
89+
### Component Layer
90+
91+
**Components:**
92+
- Consume store signals for display
93+
- Create local computed signals for component-specific derived state
94+
- Dispatch actions through service methods
95+
- Maintain minimal local state for UI-only concerns
96+
- Handle user interactions
97+
- Focus on presentation logic
98+
99+
## Decision Guidelines
100+
101+
| Concern | Location | Justification |
102+
|---------|----------|---------------|
103+
| Application data | Store | Centralized, shared across components |
104+
| Business logic | Services | Reusable, testable, independent of UI |
105+
| API communication | Services | Encapsulates external dependencies |
106+
| Data transformations | Services & Store Signals | Services for write path, Store Signals for read path |
107+
| Form state | Component local state | Temporary UI state until submission |
108+
| UI state (expanded/collapsed) | Component local state | UI-specific concerns |
109+
| Derived data calculations | Store Signals or Component signals | Global derivations in Store Signals, component-specific in local signals |
110+
| Validations | Services (for business rules), Components (for UI validation) | Business validations in services, immediate feedback in components |
111+
112+
## Best Practices
113+
114+
1. **Minimize component state** - Only use local state for UI-specific concerns
115+
2. **Keep components pure** - Focus on presentation, delegate logic to services
116+
3. **Services should be stateless** - They orchestrate but don't store state [CS-V04]
117+
4. **Global state should be normalized** - Avoid duplication and nested state
118+
5. **Use computed signals** - Derive values rather than storing calculated results [CS-S02]
119+
6. **Lazy-load state modules** - Only load state relevant to the current route
120+
7. **Dispatch one action per user intent** - Services should orchestrate complex workflows
121+
122+
## Anti-patterns to Avoid
123+
124+
1. ❌ Components mutating store directly (bypass services) [violates CS-S03]
125+
2. ❌ Components containing business logic
126+
3. ❌ Services with their own state
127+
4. ❌ Duplicating store data in component state
128+
5. ❌ Deep nesting in global state
129+
6. ❌ Storing derived data that could be computed
130+
131+
## Example Flow
132+
133+
```typescript
134+
// Component reading from store
135+
@Component({...})
136+
export class ProductListComponent {
137+
// Read directly from store signals
138+
products = inject(ProductStore).products;
139+
140+
// Local computed signal
141+
filteredProducts = computed(() =>
142+
this.products().filter(p => p.inStock)
143+
);
144+
145+
// Write through service
146+
constructor(private productService: ProductService) {}
147+
148+
addToCart(productId: string): void {
149+
this.productService.addProductToCart(productId);
150+
}
151+
}
152+
```
153+
154+
By following this architecture and data flow pattern, we create a scalable, maintainable application with clear separation of concerns and predictable state management.

‎CODING_STANDARDS/angular-state-pattern.mermaid‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
---
2+
title: Angular State Pattern - Visual Overview
3+
---
4+
%%{init: {'theme':'neutral'}}%%
5+
6+
%% NOTE: This is a supplementary visualization. For comprehensive state management guidance,
7+
%% including decision guidelines and best practices, see angular-state-architecture.md
8+
19
flowchart TB
210
subgraph "Angular Application"
311
subgraph "Global State Layer"

‎CODING_STANDARDS/documentation-map.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@
88
|----------------|----------|
99
| Quick coding rules | [angular-cheat-sheet.md](./angular-cheat-sheet.md) |
1010
| Detailed standards with examples | [angular-coding-standards.md](./angular-coding-standards.md) |
11-
| Visual architecture diagram | [angular-state-pattern.mermaid](./angular-state-pattern.mermaid) |
11+
| State architecture guide | [angular-state-architecture.md](./angular-state-architecture.md) |
12+
| Visual state flow diagram | [angular-state-pattern.mermaid](./angular-state-pattern.mermaid) |
1213
| Project-specific implementation | [CLAUDE.md](../CLAUDE.md) |
1314
| WhyTV deviations from standards | [project-overrides.md](./project-overrides.md) |
1415
| Library documentation | [/docs](../docs/) directory |
@@ -22,7 +23,8 @@ whytv/
2223
├── CODING_STANDARDS/ # Universal standards (portable)
2324
│ ├── angular-cheat-sheet.md # Quick reference with law codes
2425
│ ├── angular-coding-standards.md # Comprehensive law book
25-
│ ├── angular-state-pattern.mermaid # Visual architecture
26+
│ ├── angular-state-architecture.md # Detailed state management guide
27+
│ ├── angular-state-pattern.mermaid # Visual state flow diagram
2628
│ ├── angular_llms.txt # Angular's LLM reference
2729
│ ├── angular_llms-full.txt # Angular's full LLM docs
2830
│ ├── documentation-map.md # This file
@@ -41,7 +43,9 @@ whytv/
4143
### "I need to know how to..."
4244
- **Write Angular code** → Start with `angular-cheat-sheet.md`
4345
- **Understand a specific rule** → Look up the code in `angular-coding-standards.md`
44-
- **Understand state flow** → View `angular-state-pattern.mermaid`
46+
- **Design state architecture** → Read `angular-state-architecture.md`
47+
- **Visualize state flow** → View `angular-state-pattern.mermaid`
48+
- **Decide where code belongs** → Check Decision Guidelines in `angular-state-architecture.md`
4549
- **Work with WhyTV specifically** → Check `CLAUDE.md`
4650
- **Use a library** → Check `/docs` directory
4751

@@ -68,9 +72,15 @@ whytv/
6872
- The source of truth for all standards
6973
- 600+ lines of best practices
7074

75+
**angular-state-architecture.md**
76+
- Comprehensive state management guide
77+
- Decision guidelines table
78+
- Best practices and anti-patterns
79+
- Code examples
80+
7181
**angular-state-pattern.mermaid**
7282
- Visual representation of state flow
73-
- Shows one-way data flow pattern
83+
- Supplementary diagram to state architecture guide
7484
- Component → Service → Store → Component
7585

7686
**project-overrides.md**

‎CODING_STANDARDS/index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,17 @@ This directory contains universal Angular and TypeScript coding standards that c
1515
**Content**: Router-first architecture, components, state management, async patterns, file organization, testing
1616
**Status**: Living document - updated based on real-world usage
1717

18+
### angular-state-architecture.md
19+
**Purpose**: Comprehensive guide to state management architecture and data flow
20+
**Content**: Detailed layer responsibilities, decision guidelines table, best practices, anti-patterns
21+
**Unique Value**: Practical "where does X belong?" decision guide and concrete code examples
22+
**Integration**: Referenced by law codes CS-S01 through CS-S05
23+
1824
### angular-state-pattern.mermaid
1925
**Purpose**: Visual flowchart of the one-way state management pattern
2026
**Shows**: Component → Service → Store → Component data flow
2127
**Key Concept**: Shared state is immutable at component level, only updated via services
28+
**Note**: Supplementary visualization to angular-state-architecture.md
2229

2330
## 📖 Reference Documentation
2431

0 commit comments

Comments
 (0)