Technical Leadership & Architecture Ownership

1// Architecture Decision Record (ADR) Example
2// This is how Staff engineers document technical decisions
3
4/**
5 * ADR-007: Adopt Zustand for Feature-Level State Management
6 * 
7 * Status: Accepted
8 * Date: 2025-01-15
9 * Decision Makers: [Staff Eng, Tech Lead, Senior Eng]
10 * 
11 * Context:
12 * - Current Redux store has 45 slices, 12K lines
13 * - Bundle impact: redux + toolkit + saga = 42KB gzipped
14 * - New engineers take 2 weeks to understand the state architecture
15 * - Feature teams frequently cause cross-feature state bugs
16 * 
17 * Decision:
18 * - Use Zustand for NEW feature-level state (isolated per feature)
19 * - Keep Redux for cross-cutting global state (auth, config, theme)
20 * - Migrate existing features incrementally (priority: most-changed first)
21 * 
22 * Trade-offs:
23 * + Zustand: 1.2KB, zero boilerplate, TypeScript-native
24 * + Feature isolation: no cross-feature state leaks
25 * + Faster onboarding: Zustand is simpler mental model
26 * - Two state management patterns in codebase (temporary)
27 * - Need migration tooling / codemods
28 * - Middleware patterns differ from Redux
29 * 
30 * Migration Plan:
31 * Phase 1: New features use Zustand (enforce via lint rule)
32 * Phase 2: Migrate top 5 most-changed features (Q1)
33 * Phase 3: Migrate remaining features (Q2-Q3)
34 * Phase 4: Remove Redux dependency (Q4 stretch goal)
35 * 
36 * Success Metrics:
37 * - Feature state bugs reduced by 50% (from 12/quarter to 6)
38 * - New feature setup time < 30 minutes (currently 2 hours)
39 * - Bundle size reduction: 40KB (after full migration)
40 */
41
42// Staff-level: Defining the architectural standard
43// platform/state/createFeatureStore.ts
44import { create, StateCreator } from 'zustand';
45import { devtools, persist } from 'zustand/middleware';
46import { immer } from 'zustand/middleware/immer';
47
48interface StoreConfig<T> {
49  name: string;
50  persist?: boolean;
51  enableDevtools?: boolean;
52}
53
54export function createFeatureStore<T extends object>(
55  config: StoreConfig<T>,
56  stateCreator: StateCreator<T, [['zustand/immer', never]], []>
57) {
58  let store = stateCreator;
59
60  // Apply immer for immutable updates
61  const middlewares: any[] = [immer];
62
63  // Optional persistence (for offline-first features)
64  if (config.persist) {
65    middlewares.push((fn: any) =>
66      persist(fn, {
67        name: `feature-${config.name}`,
68        // Custom storage for React Native (AsyncStorage/MMKV)
69        storage: createMMKVStorage(config.name),
70      })
71    );
72  }
73
74  // Devtools in development
75  if (__DEV__ || config.enableDevtools) {
76    middlewares.push((fn: any) =>
77      devtools(fn, { name: config.name })
78    );
79  }
80
81  return create<T>()(
82    middlewares.reduceRight((acc, mw) => mw(acc), stateCreator)
83  );
84}
85
86// Usage by any feature team — consistent patterns, zero boilerplate:
87const useCartStore = createFeatureStore(
88  { name: 'cart', persist: true },
89  (set, get) => ({
90    items: [],
91    total: 0,
92    addItem: (item) => set((state) => {
93      state.items.push(item);
94      state.total += item.price;
95    }),
96    removeItem: (id) => set((state) => {
97      const idx = state.items.findIndex(i => i.id === id);
98      if (idx !== -1) {
99        state.total -= state.items[idx].price;
100        state.items.splice(idx, 1);
101      }
102    }),
103  })
104);