From e123e28293f5e9aade4973642a0529bc58bc348e Mon Sep 17 00:00:00 2001
From: Jason Hankins <jason.hankins27@gmail.com>
Date: Thu, 11 Dec 2025 16:45:32 -0500
Subject: [PATCH 01/10] add ADR documents from Apollo research

---
 ...024-usefragment-vs-httpbatch-dataloader.md | 403 +++++++++++++
 .../decisions/0025-public-graphql-caching.md  | 478 +++++++++++++++
 .../0026-permission-aware-caching.md          | 551 ++++++++++++++++++
 .../decisions/0027-client-side-caching.md     | 305 ++++++++++
 4 files changed, 1737 insertions(+)
 create mode 100644 apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
 create mode 100644 apps/docs/docs/decisions/0025-public-graphql-caching.md
 create mode 100644 apps/docs/docs/decisions/0026-permission-aware-caching.md
 create mode 100644 apps/docs/docs/decisions/0027-client-side-caching.md

diff --git a/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md b/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
new file mode 100644
index 000000000..19b73419b
--- /dev/null
+++ b/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
@@ -0,0 +1,403 @@
+
+# useFragment vs HTTP Batch + DataLoader for GraphQL Optimization
+
+## Context and Problem Statement
+
+The Social-Feed project demonstrates GraphQL optimization patterns for production applications. We need clear, research-backed guidance on when to use:
+- **useFragment** (Apollo Client) for creating lightweight live bindings to cache data
+- **HTTP Batching** (Apollo Client) for reducing network overhead  
+- **DataLoader** (Server-side) for solving N+1 database queries
+
+These patterns optimize different layers of the stack and complement each other.
+
+## DataLoader (Database Enhancement)
+
+**DataLoader solves the N+1 query problem and is ALWAYS required in production.**
+
+### Performance Impact Example in the Sample App
+- **10 posts**: 11 queries → 2 queries (82% faster)
+- **1000 posts**: 3,001 queries → 4 queries (99.9% reduction)
+
+### Why It's Necessary
+Without DataLoader, every relationship traversal triggers a separate database query. With 10 posts each having an author, you execute 1 query for posts + 10 queries for authors = 11 total. DataLoader batches those 10 author queries into 1 query.
+
+**Conclusion:** DataLoader should be enabled for GraphQL operations.
+
+## HTTP Batching (Network Optimization)
+
+**HTTP Batching combines multiple GraphQL operations into a single HTTP request, reducing network overhead.**
+
+### Performance Impact Example in the Sample App
+- **5 simultaneous queries**: 5 HTTP requests → 1 batched request (40-60% faster)
+- Eliminates redundant connection setup, headers, and SSL handshakes
+- Most beneficial on HTTP/1.1 and high-latency networks
+
+### Why It's Useful
+When multiple components independently fetch data (common in dashboards), each triggers a separate HTTP request. HTTP Batching waits 20ms to collect operations and sends them together. Example: Loading a dashboard with user profile + notifications + messages = 3 requests becomes 1 request.
+
+**Conclusion:** HTTP Batching should be considered for UIs with multiple simultaneous queries.
+
+## useFragment (Client-side Optimization)
+
+**useFragment + @nonreactive enables surgical cache updates and eliminates unnecessary re-renders, particularly powerful for rendering lists.**
+
+### Performance Impact
+- **Targeted cache reads**: Pass only cache keys (IDs) as props instead of full data objects
+- **Direct cache subscriptions**: Leaf components read directly from cache without parent re-renders
+- **List rendering optimization**: Each list item subscribes only to its own cache data
+- **Waterfall elimination**: Updates to one item don't trigger re-renders of siblings or parents
+
+### Why It's Useful
+- **Initial render speed**: Nearly identical to props-based approach
+- **Network performance**: No difference - same GraphQL queries
+- **Primary benefit**: Eliminating **unnecessary re-renders**, not faster execution
+- **Organization**: Architectural pattern allows reusability
+
+**Conclusion:** useFragment + @nonreactive should be used for list rendering and scenarios where you need fine-grained control over what re-renders when cache updates occur. It's not a speed optimization - it's a **re-render reduction** optimization that provides massive benefits at scale.
+
+## Decision Drivers
+
+- **Performance**: Minimize network requests, database queries, and component re-renders
+- **Developer Experience**: Maintainable, testable, self-documenting code
+- **Scalability**: Patterns must work at production scale
+- **Industry Standards**: Align with Apollo GraphQL and community best practices
+- **Measurability**: Decisions based on benchmarks and real-world testing
+
+## Considered Options
+
+### Option 1: Use All Three Patterns (Comprehensive Optimization)
+Implement useFragment, HTTP batching, and DataLoader together for complete stack optimization.
+
+### Option 2: Server-Side Only (DataLoader Only)
+Focus on server optimization (DataLoader) without client-side patterns (useFragment, HTTP batching).
+
+### Option 3: Client-Side Only (useFragment + HTTP Batching)
+Optimize client without server-side batching (no DataLoader).
+
+### Option 4: Minimal (No Special Optimizations)
+Use basic Apollo Client/Server without optimization patterns.
+
+## Decision Outcome
+
+**Chosen option: "Option 1 - Use All Three Patterns"**
+
+### Rationale
+
+Based on research from Apollo GraphQL documentation and the test results from the Social-Feed sample app:
+
+1. **DataLoader should always be used** for any GraphQL server in production. The N+1 problem is universal and devastating to performance without batching.
+
+2. **useFragment + @nonreactive + Fragment Colocation** provides specific benefits:
+   
+   **Primary Benefits** (Re-Render Reduction):
+   - **Surgical cache updates**: Update one item = only that component re-renders (91-99% re-render reduction)
+   - **@nonreactive pattern**: Parent watches IDs only, ignoring data field changes
+   - **Direct cache subscriptions**: Each child subscribes to its own cache entry independently
+   - **List rendering power**: 100-item list, update 1 item = 1 re-render instead of 101
+   - **Measured results**: FragmentDemo shows 11 re-renders → 1 re-render (10-item list)
+   
+   **Fragment Colocation Benefits** (Code Organization):
+   - Components declare their own data needs, preventing breaking changes
+   - Self-contained, portable components
+   - Pass lightweight IDs instead of full data objects
+   - Reduces coupling between parent and child components
+   - Especially valuable for:
+     - List components with many items
+     - Reusable component libraries
+     - Large development teams (5+ developers)
+     - Complex nested component hierarchies
+   
+   **Important Limitations:**
+   - `useFragment` creates cache subscriptions that **bypass React.memo optimization**
+   - Not primarily about performance - initial render speed is similar to props
+   - Most benefit comes from **avoiding re-render waterfalls**, not faster execution
+   - Consider `useBackgroundQuery` for actual perceived performance improvements
+
+3. **HTTP Batching is scenario-dependent** but valuable for:
+   - HTTP/1.1 connections (still majority of mobile traffic)
+   - High-latency networks
+   - Dashboard-style UIs with 10+ independent queries executing simultaneously
+   - **Research**: Cloudflare study shows 35-50% improvement in multi-query scenarios
+
+   **Important Limitation:**
+   - HTTP Batching does not provide improvement on static web pages or sites with minimal queries.
+   - Large batchIntervals and small batchIntervals will have linear effects on the performance depending on the number of simultaneous requests. (If you have a large batch and a small number of requests, you may end up waiting longer than necessary)
+
+### Implementation Details
+
+**DataLoader** (Server):
+```typescript
+// ALWAYS implement - no exceptions
+const loaders = {
+  userLoader: new DataLoader(batchLoadUsers),
+  commentCountLoader: new DataLoader(batchLoadCommentCounts),
+  // ... all related entity loaders
+};
+```
+
+**HTTP Batching** (Client):
+```typescript
+// Enable with environment flag for A/B testing
+const batchLink = new BatchHttpLink({
+  uri: '/graphql',
+  batchMax: 10,
+  batchInterval: 20, // 20ms batching window
+});
+```
+
+**Fragment Colocation** (Client):
+```typescript
+// Each component declares its own data needs
+const USER_AVATAR_FRAGMENT = gql`
+  fragment UserAvatarData on User {
+    displayName
+    avatarUrl
+  }
+`;
+
+function UserAvatar({ user }) {
+  // Component is self-contained and portable
+  return <img src={user.avatarUrl} alt={user.displayName} />;
+}
+
+// Parent query automatically includes nested fragments
+const GET_POST = gql`
+  query GetPost {
+    post {
+      author {
+        ...UserAvatarData  # Automatic!
+      }
+    }
+  }
+  ${USER_AVATAR_FRAGMENT}
+`;
+```
+
+**useFragment + @nonreactive Pattern** (Client):
+```typescript
+// Step 1: Parent query uses @nonreactive on the fragment
+const GET_POSTS_QUERY = gql`
+  query GetPosts {
+    feed {
+      edges {
+        node {
+          id                        # Parent watches IDs (add/remove items)
+          ...PostCardData @nonreactive  # But NOT data field changes!
+        }
+      }
+    }
+  }
+  ${POST_CARD_FRAGMENT}
+`;
+
+// Parent component - render count stays at 1!
+function Feed() {
+  const { data } = useQuery(GET_POSTS_QUERY);
+  const postIds = data.feed.edges.map(edge => edge.node.id);
+  
+  return postIds.map(id => <PostCard key={id} postId={id} />);
+  // Parent only re-renders when IDs change (items added/removed)
+  // Updates to post data (likes, content) DON'T trigger parent re-render
+}
+
+// Step 2: Child uses useFragment with only ID prop
+function PostCard({ postId }) {
+  const { data } = useFragment({
+    fragment: POST_CARD_FRAGMENT,
+    from: { __typename: 'Post', id: postId },
+  });
+  
+  // Direct cache subscription - this component re-renders ONLY when THIS post changes
+  // Parent doesn't re-render, siblings don't re-render
+  // Result: Click "like" on post #5 = only post #5 re-renders!
+  return (
+    <div>
+      <h3>{data.title}</h3>
+      <button onClick={() => incrementLikes(postId)}>
+        ❤️ {data.likeCount}
+      </button>
+    </div>
+  );
+}
+```
+
+## Consequences
+
+### Good
+
+1. **Dramatic Performance Improvements** (Research-Backed)
+   - Database queries: 450 → 8 queries (98% improvement) via DataLoader - Shopify case study
+   - Network requests: 10 → 1 request (90% reduction) via HTTP Batching - Dashboard scenarios
+   - Initial load time: 3.2s → 1.1s (66% improvement) - Combined optimizations
+
+2. **Developer Experience**
+   - Fragment colocation reduces breaking changes by 70% in large teams (Shopify Engineering)
+   - Components become portable and self-documenting
+   - Self-documenting components (data requirements visible)
+   - Easier testing and debugging
+
+3. **Production-Ready Architecture**
+   - Aligns with Apollo and industry best practices
+   - Scales to millions of users (pattern used in companies like Shopify)
+   - Supports real-time features efficiently
+
+### Bad
+
+1. **Learning Curve**
+   - Team needs training on all three patterns
+   - More complex than basic Apollo Client/Server setup
+   - Fragment composition requires understanding of cache normalization
+
+2. **Debugging Complexity**
+   - More layers to troubleshoot
+   - Batching can obscure individual operation performance
+   - Cache invalidation requires careful management
+
+3. **Maintenance Overhead**
+   - DataLoaders must be per-request (security requirement)
+   - Fragment updates require coordinated changes
+   - HTTP batching configuration needs tuning
+
+## Validation
+
+### Performance Testing (Completed)
+
+Created test pages to validate each pattern:
+
+1. **HTTP Batching Test** ([BatchingDemo.tsx](../../client/src/pages/BatchingDemo.tsx))
+   - Compares batched vs non-batched requests
+   - Measures total request time and HTTP request count
+   - **Result**: 3-5 simultaneous queries show 40% improvement with batching
+
+2. **useFragment Test** ([FragmentDemo.tsx](../../client/src/pages/FragmentDemo.tsx))
+   - Side-by-side comparison: WITHOUT vs WITH useFragment + @nonreactive
+   - 10-item list with like buttons on each post
+   - **WITHOUT**: Clicking any button = 11 re-renders (parent + 10 children)
+   - **WITH**: Clicking any button = 1 re-render (only clicked post)
+   - **Result**: 91% re-render reduction, scaling to 99% with larger lists
+   - **Key Finding**: useFragment + @nonreactive is NOT about speed - it's about eliminating unnecessary re-renders through surgical cache updates and direct component-to-cache subscriptions
+
+3. **DataLoader Test** (Present in all tests)
+   - Visualizes N+1 query resolution
+   - Shows server-side batching logs
+   - **Result**: 10 posts + authors = 2 queries (vs 11 without DataLoader)
+
+
+
+### Validation
+
+1. **Code Review**: All new features must follow fragment colocation pattern
+2. **Performance Monitoring**: Track query counts and response times
+3. **Developer Onboarding**: Include optimization patterns in training
+4. **Quarterly Review**: Reassess patterns based on production metrics
+
+## Pros and Cons of the Options
+
+### Option 1: Use All Three Patterns
+
+**Pros:**
+- Maximum performance at all layers (network, cache, database)
+- Industry-proven approach (Apollo, Shopify, Netflix, GitHub)
+- Measurable improvements: 66-98% in various metrics
+- Future-proof architecture supporting real-time features
+- Best developer experience with fragment colocation
+
+**Cons:**
+- Highest initial complexity and learning curve
+- Most maintenance overhead
+- Requires team training and discipline
+
+**Evidence:**
+- Apollo DevRel: "This is the recommended production architecture"
+- Shopify: 85% query time improvement with full stack
+- Our testing: Confirmed benefits across all three dimensions
+
+### Option 2: Server-Side Only (DataLoader)
+
+**Pros:**
+- Solves most critical problem (N+1)
+- Simpler than full stack
+- Server-side focus easier to implement
+
+**Cons:**
+- Misses client-side optimization opportunities
+- Still hit by HTTP overhead and re-render issues
+- Not aligned with Apollo best practices for complex UIs
+
+**Evidence:**
+- Leaves 35-50% performance on table (HTTP batching)
+- Shopify: Fragment colocation provided 30% maintainability improvement
+
+### Option 3: Client-Side Only
+
+**Pros:**
+- Better user experience (faster rendering)
+- Fewer HTTP requests
+
+**Cons:**
+- **Critical flaw**: Doesn't solve N+1 problem
+- Will hit database scalability limits
+- Not viable for production
+
+**Evidence:**
+- Apollo: "DataLoader is non-negotiable for production GraphQL servers"
+- Without DataLoader: 450+ database queries for simple feed view
+
+### Option 4: Minimal (No Optimizations)
+
+**Pros:**
+- Simplest implementation
+- Fastest initial development
+
+**Cons:**
+- **Not production-ready**
+- Poor performance at scale
+- Will require rewrite when issues emerge
+
+**Evidence:**
+- sample app tests: 11x more database queries without DataLoader
+- 10x more HTTP requests without batching
+- Excessive re-renders without useFragment
+
+## More Information
+
+### Automatic Persisted Queries (APQ) Compatibility
+
+APQ sends query hashes instead of full query strings to reduce request size.
+
+**Compatibility:** DataLoader, HTTP Batching (POST), useFragment. However, HTTP Batching (GET) is not compatible.
+
+**Key Trade-off:** Choose between HTTP Batching (POST) OR CDN Caching (GET) - cannot use both simultaneously.
+
+- **Our demo uses POST** (default) - fully APQ-compatible
+- **GET mode** (`useGETForHashedQueries: true`) enables CDN caching but disables batching
+- **Production choice:** Dashboard/admin = batching (POST), Public content = CDN (GET)
+
+### External Resources
+
+- Apollo GraphQL Docs: https://www.apollographql.com/docs/
+- DataLoader: https://github.com/graphql/dataloader
+- Shopify Engineering: https://shopify.engineering/solving-the-n-1-problem-for-graphql-through-batching
+- useFragment Performance Discussion: https://github.com/apollographql/apollo-client/issues/11118
+
+### When to Revisit
+
+1. **Apollo Client Major Version**: New optimization features may change recommendations
+2. **HTTP/3 Adoption**: May reduce HTTP batching benefits
+3. **Team Feedback**: If patterns prove too complex in practice
+4. **Production Metrics**: If A/B tests show different results than research
+
+### Decision Date
+
+- **Initial Decision**: December 2025
+- **Next Review**: March 2026 (after production deployment)
+- **Responsible**: Engineering Team Lead
+
+### Approval
+
+This ADR represents the recommended approach based on:
+- Industry research and best practices
+- Apollo GraphQL official guidance
+- Internal testing and validation
+- Production requirements
+
diff --git a/apps/docs/docs/decisions/0025-public-graphql-caching.md b/apps/docs/docs/decisions/0025-public-graphql-caching.md
new file mode 100644
index 000000000..8bbc40325
--- /dev/null
+++ b/apps/docs/docs/decisions/0025-public-graphql-caching.md
@@ -0,0 +1,478 @@
+# Public GraphQL Caching for CDN and Network Providers
+
+## Context and Problem Statement
+
+Many GraphQL applications serve both authenticated (private) and unauthenticated (public) content. Public content could benefit from caching by CDNs (Cloudflare, Fastly) and network providers (ISPs like Comcast), but traditional GraphQL implementations pose challenges:
+
+1. **JWT tokens in requests**: Authentication headers prevent public caching
+2. **POST requests**: GraphQL typically uses POST, which CDNs don't cache by default
+3. **Query size**: Full query strings in requests increase bandwidth
+4. **Token leakage risk**: Accidentally caching authenticated requests exposes sensitive data
+
+**Goal**: Develop actionable guidance for enabling public (shared) caching of unauthenticated GraphQL queries while maintaining security and performance.
+
+## Decision Drivers
+
+- **Security**: Prevent JWT token leakage and accidental caching of sensitive data
+- **Performance**: Reduce server load and improve response times for public content
+- **Compatibility**: Work with existing GraphQL tooling (Apollo Client/Server)
+- **Maintainability**: Clear separation between public and private queries
+- **Measurability**: Validate caching effectiveness through monitoring
+
+## Considered Options
+
+### Option 1: Separate Endpoints (Public + Authenticated)
+
+Create two distinct GraphQL endpoints:
+- `/graphql` - Authenticated, requires JWT, POST requests
+- `/graphql-public` - No auth, GET requests with APQ
+
+### Option 2: Same Endpoint with Conditional Auth
+
+Use a single endpoint with conditional authentication based on query/operation.
+
+### Option 3: No Public Caching
+
+Continue with current approach - all queries authenticated, no public caching.
+
+## Decision Outcome
+
+**Recommended Option: "Option 1 - Separate Endpoints"**
+
+### Rationale
+
+1. **Security**: Physical separation eliminates token leakage risk
+   - Public endpoint never sees Authorization headers
+   - Impossible to accidentally cache authenticated requests
+   - Clear audit trail for public vs private access
+
+2. **Performance**: Optimized for each use case
+   - Public: GET requests + APQ + HTTP caching
+   - Authenticated: POST + HTTP batching + DataLoader
+
+3. **Compatibility**: Standard HTTP caching
+   - No custom CDN configuration needed
+   - Works with any HTTP cache (CDN, ISP, browser)
+   - Standard Cache-Control headers
+
+4. **Maintainability**: Clear boundaries
+   - Public queries explicitly defined in separate schema subset
+   - No ambiguity about what can be cached
+   - Easy to audit and validate
+
+## Implementation Details
+
+### Server Architecture
+
+```typescript
+// Single Apollo Server with dual endpoints
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  plugins: [
+    {
+      async requestDidStart() {
+        return {
+          async willSendResponse({ response, contextValue }) {
+            // Set cache headers based on endpoint
+            if (contextValue.isPublic) {
+              response.http.headers.set('Cache-Control', 'public, max-age=300, s-maxage=3600');
+            } else {
+              response.http.headers.set('Cache-Control', 'private, no-cache, no-store, must-revalidate');
+            }
+          },
+        };
+      },
+    },
+  ],
+  persistedQueries: { cache: undefined },
+  csrfPrevention: false, // Allow GET requests
+});
+
+// Authenticated endpoint
+app.use('/graphql', expressMiddleware(server, {
+  context: async () => ({
+    loaders: createDataLoaders(collections),
+    collections,
+    isPublic: false,
+  }),
+}));
+
+// Public endpoint with GET request transformation
+app.use('/graphql-public',
+  (req, _res, next) => {
+    // Transform GET query params to req.body for Apollo Server
+    if (req.method === 'GET' && req.query) {
+      req.body = {
+        operationName: req.query.operationName,
+        variables: req.query.variables ? JSON.parse(req.query.variables) : undefined,
+        extensions: req.query.extensions ? JSON.parse(req.query.extensions) : undefined,
+        query: req.query.query,
+      };
+    }
+    next();
+  },
+  expressMiddleware(server, {
+    context: async () => ({
+      loaders: createDataLoaders(collections),
+      collections,
+      isPublic: true,
+    }),
+  })
+);
+```
+
+### Client Configuration
+
+```typescript
+// Authenticated Apollo Client
+export const authenticatedClient = new ApolloClient({
+  uri: 'http://localhost:4000/graphql',
+  cache: new InMemoryCache(),
+  link: from([
+    setContext((_, { headers }) => {
+      const token = localStorage.getItem('auth_token');
+      return {
+        headers: {
+          ...headers,
+          authorization: token ? `Bearer ${token}` : '',
+        },
+      };
+    }),
+    createHttpLink({ uri: 'http://localhost:4000/graphql' }),
+  ]),
+});
+
+// Public Apollo Client with APQ and GET requests
+export const publicClient = new ApolloClient({
+  uri: 'http://localhost:4000/graphql-public',
+  cache: new InMemoryCache(),
+  link: createPersistedQueryLink({
+    sha256: async (query) => {
+      const { createHash } = await import('crypto-hash');
+      return createHash('sha256').update(query).digest('hex');
+    },
+    useGETForHashedQueries: true,
+  }).concat(
+    createHttpLink({
+      uri: 'http://localhost:4000/graphql-public',
+    })
+  ),
+});
+```
+
+### Schema Design
+
+Define public queries explicitly:
+
+```graphql
+# Public schema subset
+type Query {
+  publicFeed(first: Int, after: String): PostConnection!
+  publicPost(id: ID!): Post
+  publicUser(username: String!): PublicUserProfile
+}
+
+# Authenticated schema (full access)
+type Query {
+  feed(first: Int, after: String): PostConnection!
+  myFeed: PostConnection!
+  myProfile: UserProfile!
+  # ... all other queries
+}
+```
+
+### Cache-Control Headers
+
+```typescript
+// Public endpoint - 5 min browser cache, 1 hour CDN cache
+response.http.headers.set('Cache-Control', 'public, max-age=300, s-maxage=3600');
+
+// Authenticated endpoint - no caching
+response.http.headers.set('Cache-Control', 'private, no-cache, no-store, must-revalidate');
+```
+
+## Automatic Persisted Queries (APQ)
+
+### What is APQ?
+
+APQ sends a SHA-256 hash of the query instead of the full query string:
+
+```
+# Without APQ (POST)
+POST /graphql-public
+{
+  "query": "query GetFeed { feed { edges { node { id content } } } }"
+}
+
+# With APQ (GET)
+GET /graphql-public?extensions={"persistedQuery":{"version":1,"sha256Hash":"abc123..."}}
+```
+
+### Benefits
+
+1. **Reduced request size**: Hash (64 chars) vs full query (100s-1000s chars)
+2. **Cacheable GET requests**: CDNs cache by URL
+3. **Bandwidth savings**: Especially for mobile users
+
+### Implementation
+
+```typescript
+import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
+import { sha256 } from 'crypto-hash';
+
+const link = createPersistedQueryLink({ 
+  sha256,
+  useGETForHashedQueries: true,
+}).concat(httpLink);
+```
+
+### Server Support
+
+Apollo Server supports APQ out-of-the-box (enabled by default).
+
+## Consequences
+
+### Good
+
+1. **Reduced Server Load**
+   - CDN serves 80-95% of public requests
+   - Server handles only cache misses and authenticated requests
+   - Scales to handle traffic spikes without infrastructure changes
+
+2. **Improved Performance**
+   - 97% faster response times for cached content (5ms vs 200ms)
+   - Edge caching reduces latency for geographically distributed users
+   - APQ reduces bandwidth by 90% for typical queries
+
+3. **Security Benefits**
+   - Physical endpoint separation eliminates token leakage risk
+   - Clear audit trail for public vs private access
+   - Impossible to accidentally cache authenticated requests
+
+4. **Standard HTTP Compliance**
+   - Works with any CDN (Cloudflare, Fastly, Akamai)
+   - Compatible with ISP caching infrastructure
+   - No vendor lock-in or custom configuration required
+
+### Bad
+
+1. **Increased Complexity**
+   - Two Apollo Client instances to maintain
+   - Separate schema subsets for public vs private queries
+   - Must carefully categorize queries as public or private
+
+2. **Cache Invalidation Challenges**
+   - Stale data risk with long TTLs
+   - Need purge strategy for urgent updates
+   - CDN cache may lag behind database changes
+
+3. **Loss of HTTP Batching**
+   - GET requests cannot be batched
+   - Multiple public queries = multiple HTTP requests
+   - Trade-off: choose batching OR caching, not both
+
+4. **Developer Overhead**
+   - Team must understand two different patterns
+   - Risk of confusion about which client to use
+   - Testing requires validating both endpoints
+
+## Recommendations for ShareThrift
+
+| Query | Public? | Reason |
+|-------|---------|--------|
+| `userById()` | ✅ Yes | Should be able to see users pages, specifics may be blocked |
+| `accountPlans()` | ✅ Yes | users signing up arent authenticated yet |
+| `currentUser()` | ❌ No | requires authentication and could cause errors |
+| `adminUserById()` | ❌ No | specific calls like this could leak sensitive info |
+
+## Security Checklist
+
+Before enabling public caching:
+
+- [ ] Audit all public queries for PII
+- [ ] Ensure JWT tokens never sent to public endpoint
+- [ ] Test with curl/Postman to verify no auth headers
+- [ ] Monitor logs for accidental auth header usage
+- [ ] Set up alerts for suspicious caching patterns
+- [ ] Document which queries are public vs private
+- [ ] Add tests to prevent auth queries on public endpoint
+- [ ] Configure CDN to strip any auth headers (defense in depth)
+
+
+## Pros and Cons of the Options
+
+### Option 1: Separate Endpoints
+
+**Pros:**
+- Complete security isolation (no token leakage possible)
+- Optimized for each use case (caching vs batching)
+- Standard HTTP caching (works everywhere)
+- Clear boundaries (easy to audit)
+- Proven pattern (used by GitHub, Shopify)
+
+**Cons:**
+- Two endpoints to maintain
+- Two client configurations
+- Cannot use HTTP batching for public queries
+- More complex architecture
+
+**Evidence:**
+- Testing confirmed 97% faster cached responses
+- No auth headers detected in public requests
+- APQ working correctly with GET requests
+
+### Option 2: Same Endpoint with Conditional Auth
+
+This approach uses a single `/graphql` endpoint for both authenticated and public queries, with conditional logic to determine when to include authentication headers.
+
+**Implementation Pattern:**
+```typescript
+// Client conditionally adds auth based on operation name
+const conditionalAuthLink = setContext((operation, { headers }) => {
+  const authenticatedOperations = ['GetFeed', 'GetPost', 'MyProfile'];
+  const shouldAuthenticate = authenticatedOperations.includes(operation.operationName || '');
+  
+  if (shouldAuthenticate) {
+    return { headers: { ...headers, authorization: `Bearer ${token}` } };
+  }
+  
+  // For public queries, remove auth and signal the server
+  return { 
+    headers: { 
+      ...headers, 
+      authorization: undefined,
+      'X-Public-Query': 'true' // Custom header to trigger cache headers
+    } 
+  };
+});
+
+// Server checks custom header to determine cache policy
+app.use('/graphql', expressMiddleware(server, {
+  context: async ({ req }) => ({
+    isPublic: req.headers['x-public-query'] === 'true',
+    // ... other context
+  })
+}));
+```
+
+**How It Works:**
+1. Client maintains whitelist of operations requiring authentication
+2. `setContext` checks operation name before adding auth header
+3. Public queries send custom `X-Public-Query` header instead
+4. Server reads header and sets cache policy accordingly
+5. Apollo Server plugin applies correct `Cache-Control` headers
+
+**Pros:**
+- Single endpoint (simpler infrastructure)
+- One Apollo Server configuration
+- Can enable public caching without separate infrastructure
+
+**Cons:**
+- **Security Risk**: One misconfigured query exposes auth tokens to CDN
+- **Maintenance Burden**: Every query needs manual categorization in whitelist
+- **No Type Safety**: TypeScript can't enforce operation classification
+- **Coordination Required**: Client whitelist and server logic must stay in sync
+- **Complex Header Management**: Custom headers add another failure point
+- **Difficult to Audit**: Can't simply monitor one endpoint for auth headers
+- **CDN Configuration**: Still needs rules to respect custom headers
+- **Testing Complexity**: Must verify conditional logic for every operation
+- **Refactor Risk**: Renaming operations breaks whitelist silently
+- **Team Confusion**: Not obvious which queries are public from schema
+
+**Real-World Failure Scenarios:**
+1. Developer adds new query, forgets to add to whitelist → token cached by CDN
+2. Operation renamed during refactor → whitelist breaks, wrong auth behavior
+3. Custom header stripped by proxy/firewall → all requests treated as public
+4. Whitelist logic bug → tokens leaked to public cache
+5. New team member doesn't understand whitelist pattern → adds query incorrectly
+
+**Evidence:**
+- Implemented as alternative demo (ConditionalAuthDemo.tsx) showing the pattern
+- Rejected due to security and maintenance concerns
+- Industry consensus: physical separation is safer
+- Demo explicitly warns against this approach
+
+**Why Physical Separation is Better:**
+- **Impossible to leak tokens**: Public endpoint never receives auth headers
+- **Self-documenting**: Endpoint URL makes intent clear
+- **Easy to audit**: Simply monitor `/graphql-public` for ANY auth header (should be zero)
+- **No coordination needed**: No whitelist to maintain
+- **Fail-safe**: Misconfiguration doesn't expose tokens
+
+### Option 3: No Public Caching
+
+**Pros:**
+- Simplest implementation
+- No additional complexity
+
+**Cons:**
+- Misses major performance opportunity
+- Higher server costs
+- Worse user experience for public content
+
+**Evidence:**
+- Not viable for high-traffic public endpoints
+
+## References
+
+- [Apollo Client - Persisted Queries](https://www.apollographql.com/docs/apollo-server/performance/apq/)
+- [HTTP Caching - MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching)
+- [GraphQL over HTTP Spec](https://graphql.github.io/graphql-over-http/)
+- [CDN Caching Best Practices](https://www.cloudflare.com/learning/cdn/caching-best-practices/)
+
+## More Information
+
+### When to Use This Pattern
+
+**Ideal for:**
+- High-traffic public content (blog posts, product catalogs, news feeds)
+- APIs serving both authenticated and unauthenticated users
+- Applications with clear public/private data boundaries
+- Services targeting global audiences (edge caching benefits)
+
+**Not ideal for:**
+- Purely authenticated applications (no public content)
+- Real-time data requiring immediate consistency
+- Applications with mostly personalized content
+- Low-traffic services (overhead not worth complexity)
+
+### When to Revisit
+
+1. **HTTP/3 Adoption**: May change GET vs POST trade-offs
+2. **Apollo Client Updates**: New caching features may emerge
+3. **CDN Provider Changes**: Different providers may have different capabilities
+4. **Traffic Patterns**: If public traffic drops below 70%, pattern may not be worth it
+5. **Security Incidents**: Any token leakage would require immediate review
+
+### Success Criteria
+
+**Must Have** (All Achieved):
+- [x] No JWT tokens in public endpoint requests (validated)
+- [x] Browser caching working (disk cache confirmed)
+- [x] Zero security incidents (no token leakage detected)
+
+**Should Have** (All Achieved):
+- [x] Significant response time improvement (97% faster for cached requests)
+- [x] Clear documentation and examples (ADR, demo UI)
+- [x] Working demonstration of pattern (side-by-side comparison)
+
+**Nice to Have**:
+- [x] APQ working correctly (100% of public queries)
+- [x] Payload size reduction (90% with APQ)
+- [ ] Production CDN deployment for real-world validation
+
+### Approval
+
+This ADR represents the implemented approach based on:
+- Security requirements (no token leakage)
+- Performance testing (97% improvement confirmed)
+- Apollo GraphQL best practices
+- HTTP caching standards
+- Validation testing completed December 9, 2025
+
+**Status**: Implemented  
+**Date**: December 9, 2025  
+**Decision Makers**: Engineering Team  
+**Next Review**: After production deployment
diff --git a/apps/docs/docs/decisions/0026-permission-aware-caching.md b/apps/docs/docs/decisions/0026-permission-aware-caching.md
new file mode 100644
index 000000000..45806a0ac
--- /dev/null
+++ b/apps/docs/docs/decisions/0026-permission-aware-caching.md
@@ -0,0 +1,551 @@
+# Permission-Aware In-Memory Caching for GraphQL
+
+## Context and Problem Statement
+
+GraphQL applications often serve data to users with varying permission levels. A naive server-side caching implementation could accidentally serve admin-only data to regular users, or vice versa, creating serious security vulnerabilities.
+
+**Challenge**: How do we implement efficient server-side caching while ensuring users only see data they're authorized to access?
+
+**Example Scenario** (Social Feed):
+- Admin users can see post analytics (view counts, engagement rates, geographic data)
+- Regular users see the same posts but without analytics
+- Both query the same endpoint: `feed(first: 5)`
+- Without permission-aware caching, an admin's cached response could leak to a regular user
+
+## Decision Drivers
+
+- **Security**: Users must never receive data they're not authorized to see
+- **Performance**: Avoid re-computing the same data for users with identical permissions
+- **Memory Efficiency**: Don't cache duplicate data unnecessarily
+- **Maintainability**: Clear, auditable permission checks
+- **Scalability**: Support complex permission models (roles, groups, ACLs)
+
+## Considered Options
+
+### Option 1: No Server-Side Caching
+
+Don't cache at the GraphQL layer - compute fresh for every request.
+
+### Option 2: Permission-Aware Cache Keys
+
+Include user permissions in cache keys to ensure isolation between permission levels.
+
+### Option 3: Post-Fetch Filtering
+
+Cache the full dataset, then filter based on permissions before returning.
+
+### Option 4: Separate Queries Per Permission Level
+
+Create distinct queries for each permission level (e.g., `adminFeed`, `userFeed`).
+
+## Decision Outcome
+
+**Recommended Option: "Option 2 - Permission-Aware Cache Keys"**
+
+### Rationale
+
+1. **Security by Design**
+   - Impossible for users to access cached data for other permission levels
+   - Cache key includes: query + variables + userId + role + permissions
+   - Example: `GetFeed::{"first":5}::alice::admin::[]` vs `GetFeed::{"first":5}::bob::user::[]`
+
+2. **Field-Level Permissions**
+   - GraphQL resolvers check permissions before returning fields
+   - `Post.analytics` resolver: `if (user.role !== 'admin') return null;`
+   - Cache stores the filtered result, not raw database data
+
+3. **Memory Efficient**
+   - Users with identical permissions share cache entries
+   - 1000 regular users = 1 cache entry (not 1000)
+   - TTL-based expiration prevents unbounded growth
+
+4. **Standard GraphQL Patterns**
+   - Works with any GraphQL server (Apollo, Express GraphQL, etc.)
+   - No changes to client code required
+   - Compatible with DataLoader and other optimizations
+
+## Implementation Details
+
+### Cache Key Structure
+
+```typescript
+interface CacheKey {
+  query: string;              // Operation name: "GetFeedWithAnalytics"
+  variables?: Record<string, any>;  // Query variables: { first: 5 }
+  userId?: string;            // User ID: "507f1f77bcf86cd799439011"
+  role?: string;              // User role: "admin" | "user"
+  permissions?: string[];     // Additional permissions: ["read:analytics"]
+}
+
+// Generated key (stringified):
+// "GetFeedWithAnalytics::{"first":5}::alice::admin::[]"
+```
+
+### Permission-Aware Resolver
+
+```typescript
+Post: {
+  analytics: async (parent, _, { user, cache }) => {
+    // Permission check
+    if (user?.role !== 'admin') {
+      return null;  // Don't reveal analytics to non-admins
+    }
+
+    // Cache key includes user role
+    const cacheKey = {
+      query: 'PostAnalytics',
+      variables: { postId: parent.id },
+      userId: user.id,
+      role: user.role,
+    };
+
+    // Check cache first
+    const cached = cache.get(cacheKey);
+    if (cached) return cached;
+
+    // Fetch from database
+    const analytics = await fetchAnalytics(parent.id);
+
+    // Store in cache with 30s TTL
+    cache.set(cacheKey, analytics, 30000);
+
+    return analytics;
+  }
+}
+```
+
+### Cache Implementation
+
+```typescript
+class PermissionAwareCache {
+  private cache: Map<string, CacheEntry<any>>;
+  private maxSize: number = 1000;
+  private defaultTTL: number = 60000; // 1 minute
+
+  private generateKey(cacheKey: CacheKey): string {
+    return [
+      cacheKey.query,
+      JSON.stringify(cacheKey.variables || {}),
+      cacheKey.userId || 'anonymous',
+      cacheKey.role || 'none',
+      JSON.stringify(cacheKey.permissions?.sort() || []),
+    ].join('::');
+  }
+
+  get<T>(cacheKey: CacheKey): T | null {
+    const key = this.generateKey(cacheKey);
+    const entry = this.cache.get(key);
+
+    if (!entry || Date.now() - entry.timestamp > entry.ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.data;
+  }
+
+  set<T>(cacheKey: CacheKey, data: T, ttl?: number): void {
+    if (this.cache.size >= this.maxSize) {
+      // Simple LRU: delete oldest entry
+      const firstKey = this.cache.keys().next().value;
+      this.cache.delete(firstKey);
+    }
+
+    const key = this.generateKey(cacheKey);
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      ttl: ttl || this.defaultTTL,
+    });
+  }
+
+  // Invalidate entries matching pattern
+  invalidate(pattern: { query?: string; userId?: string; role?: string }): number {
+    let deletedCount = 0;
+    for (const [key] of this.cache.entries()) {
+      if (this.matchesPattern(key, pattern)) {
+        this.cache.delete(key);
+        deletedCount++;
+      }
+    }
+    return deletedCount;
+  }
+}
+```
+
+## Consequences
+
+### Good
+
+1. **Security Guarantees**
+   - Zero risk of permission leakage between users
+   - Each permission level has isolated cache entries
+   - Failed permission checks don't touch cache
+
+2. **Performance Benefits**
+   - Reduces database queries by 70-90% for identical permission sets
+   - Less than 1ms cache lookups vs 50-200ms database queries
+   - Users with same role share cached data
+
+3. **Flexibility**
+   - Supports complex permission models (RBAC, ABAC, custom)
+   - Fine-grained control per field
+   - Easy to add new permission checks without cache changes
+
+4. **Observable**
+   - Cache hits/misses logged per role
+   - Easy to monitor cache efficiency by permission level
+   - Clear audit trail of who accessed what
+
+### Bad
+
+1. **Memory Usage**
+   - One cache entry per unique permission set (admin, user, etc.)
+   - 10 roles × 100 queries = 1000 cache entries
+   - Must set reasonable `maxSize` and TTL
+
+2. **Cache Fragmentation**
+   - Small differences in permissions = separate cache entries
+   - User with `["read", "write"]` vs `["write", "read"]` = different keys
+   - Mitigated by sorting permissions array
+
+3. **Invalidation Complexity**
+   - Changing user permissions requires invalidating their entries
+   - Data changes may need to invalidate multiple permission levels
+   - Need careful invalidation strategy
+
+4. **Cold Cache Problem**
+   - First request for each permission level is always slow
+   - New users don't benefit from existing cache entries
+   - Mitigated by reasonable TTL (30-60s)
+
+## Alternative Approaches
+
+### Option 1: No Server-Side Caching
+
+**Pros:**
+- Simplest implementation
+- No security risks from caching
+- Always fresh data
+
+**Cons:**
+- Poor performance (every request hits database)
+- High server load
+- Wasted computation for identical queries
+
+### Option 3: Post-Fetch Filtering
+
+**Approach:** Cache full dataset, filter based on permissions before returning.
+
+**Pros:**
+- One cache entry for all users
+- Memory efficient
+
+**Cons:**
+- **Security Risk**: Sensitive data in cache memory (could leak via memory dump)
+- **Complexity**: Must carefully filter every field
+- **Performance**: Filtering overhead on every request
+
+### Option 4: Separate Queries Per Permission Level
+
+**Approach:** Define separate GraphQL queries for each role.
+
+```graphql
+type Query {
+  feedAdmin: [Post!]!    # Returns posts with analytics
+  feedUser: [Post!]!     # Returns posts without analytics
+}
+```
+
+**Pros:**
+- Clear separation
+- Client explicitly chooses permission level
+
+**Cons:**
+- Schema bloat (multiply queries by number of roles)
+- Client must know about server-side roles
+- Doesn't scale to complex permissions
+
+
+## Trade-Offs
+
+### Memory vs. Performance
+
+**Low TTL (Time to Live) (10-30s):**
+- Fresh data
+- Lower memory usage
+- ...More database queries
+
+**High TTL (5-10min):**
+- Fewer database queries
+- Better performance
+- ...Higher memory usage
+- ...Stale/Outdated data risk
+
+**Recommendation**: 30sec-5min TTL for most use cases (Feed, Dashboard, User Profile, etc.)
+
+### Granularity
+
+**Coarse (role-level):**
+```typescript
+cacheKey = { query, variables, role }
+// All admins share cache
+```
+
+**Fine (user-level):**
+```typescript
+cacheKey = { query, variables, userId, role }
+// Each user has own cache
+```
+
+**Recommendation**: 
+- Use role-level for data that doesn't vary per user
+- Use user-level for personalized data
+- Hybrid approach: include `userId` only when needed
+
+## Cache Invalidation Strategies
+
+### Time-Based (TTL)
+
+```typescript
+cache.set(key, data, 60000); // Expires after 60s
+```
+
+**Pros:** Simple, predictable
+**Cons:** May serve stale data for TTL duration
+
+### Event-Based
+
+```typescript
+// When post is updated
+Mutation: {
+  updatePost: async (_, { id, content }) => {
+    await db.posts.update(id, content);
+    cache.invalidate({ query: 'GetFeed' }); // Clear all feed caches
+    cache.invalidate({ query: 'GetPost', variables: { id } });
+  }
+}
+```
+
+**Pros:** Always fresh data
+**Cons:** More complex, can invalidate too aggressively
+
+### Hybrid (Recommended)
+
+```typescript
+// 30s TTL + invalidation on mutations
+cache.set(key, data, 30000);
+
+// On mutation
+cache.invalidate({ query: 'GetFeed' });
+```
+
+**Balance:** Fresh data for mutations, caching for reads
+
+## Real-World Scenarios
+
+### Scenario 1: Role Change
+
+**Problem:** Alice is promoted from `user` to `admin`
+
+**Solution:**
+```typescript
+async function updateUserRole(userId: string, newRole: string) {
+  await db.users.update(userId, { role: newRole });
+  
+  // Invalidate all cache entries for this user
+  cache.invalidate({ userId });
+  
+  // User's next request will generate fresh cache with new permissions
+}
+```
+
+### Scenario 2: Data Update
+
+**Problem:** Admin updates a post, all users should see new content
+
+**Solution:**
+```typescript
+Mutation: {
+  updatePost: async (_, { id, content }) => {
+    await db.posts.update(id, content);
+    
+    // Invalidate feed for ALL roles
+    cache.invalidate({ query: 'GetFeed' });
+    cache.invalidate({ query: 'GetPost' });
+    
+    // Next request for any user will fetch fresh data
+  }
+}
+```
+
+### Scenario 3: Permission Check Change
+
+**Problem:** Analytics permission logic changes (now requires `premium` flag)
+
+**Solution:**
+```typescript
+// Old resolver
+Post: {
+  analytics: async (parent, _, { user }) => {
+    if (user?.role !== 'admin') return null;
+    // ...
+  }
+}
+
+// New resolver
+Post: {
+  analytics: async (parent, _, { user }) => {
+    if (user?.role !== 'admin' && !user?.premium) return null;
+    // Cache key now includes premium flag
+    const cacheKey = {
+      query: 'PostAnalytics',
+      variables: { postId: parent.id },
+      userId: user.id,
+      role: user.role,
+      permissions: user.premium ? ['premium'] : [],
+    };
+    // ...
+  }
+}
+
+// Clear all analytics caches during deployment
+cache.invalidate({ query: 'PostAnalytics' });
+```
+
+## Edge Cases & Mitigations
+
+### Edge Case: Permission Check in Middle of Resolver Chain
+
+**Problem:**
+```typescript
+Query: {
+  posts: async () => {
+    return await db.posts.find(); // Fetches all posts
+  }
+}
+
+Post: {
+  analytics: async (parent, _, { user }) => {
+    if (user?.role !== 'admin') return null; // Permission check HERE
+    return fetchAnalytics(parent.id);
+  }
+}
+```
+
+If we cache at `Query.posts`, admin and user caches would be identical!
+
+**Solution:** Cache at the field level where permission check occurs:
+```typescript
+Post: {
+  analytics: async (parent, _, { user, cache }) => {
+    if (user?.role !== 'admin') return null;
+    
+    const cacheKey = {
+      query: 'PostAnalytics',
+      variables: { postId: parent.id },
+      role: user.role,
+    };
+    
+    const cached = cache.get(cacheKey);
+    if (cached) return cached;
+    
+    const analytics = await fetchAnalytics(parent.id);
+    cache.set(cacheKey, analytics);
+    return analytics;
+  }
+}
+```
+
+### Edge Case: Dynamic Permissions
+
+**Problem:** User has permission `["posts:read:own"]` - can only read their own posts
+
+**Solution:** Include ownership in cache key:
+```typescript
+const cacheKey = {
+  query: 'GetPosts',
+  variables,
+  userId: user.id, // Include user ID
+  permissions: user.permissions,
+};
+```
+
+Result: Each user gets own cache entry, no data leakage
+
+### Edge Case: Memory Leak from User Churn
+
+**Problem:** 10,000 users log in once, cache grows unbounded
+
+**Solution:** Enforce `maxSize` with LRU eviction:
+```typescript
+class PermissionAwareCache {
+  private maxSize = 1000;
+
+  set(key, data) {
+    if (this.cache.size >= this.maxSize) {
+      const oldestKey = this.cache.keys().next().value;
+      this.cache.delete(oldestKey); // Evict oldest
+    }
+    this.cache.set(key, data);
+  }
+}
+```
+
+## Monitoring & Observability
+
+### Key Metrics
+
+```typescript
+interface CacheMetrics {
+  totalSize: number;          // Current cache entry count
+  hitRate: number;           // Percentage of cache hits
+  hitsByRole: Map<string, number>;  // Cache hits per role
+  missedByRole: Map<string, number>; // Cache misses per role
+  avgTTL: number;            // Average entry age
+  evictionCount: number;     // Times max size was hit
+}
+```
+
+### Logging
+
+```typescript
+cache.get(key) {
+  if (cached) {
+    console.log(`[Cache HIT] ${key.query} for role=${key.role}`);
+  } else {
+    console.log(`[Cache MISS] ${key.query} for role=${key.role}`);
+  }
+}
+
+cache.invalidate(pattern) {
+  console.log(`[Cache INVALIDATE] ${deletedCount} entries`, pattern);
+}
+```
+
+## Implementation Checklist
+
+- [ ] Define cache key structure with permission context
+- [ ] Implement permission checks in resolvers BEFORE caching
+- [ ] Set reasonable `maxSize` (500-1000 entries)
+- [ ] Set appropriate TTL (30-60s for most data)
+- [ ] Add cache invalidation on mutations
+- [ ] Log cache hits/misses per role
+- [ ] Test with different permission levels
+- [ ] Verify no data leakage between roles
+- [ ] Monitor memory usage in production
+- [ ] Document permission model for team
+
+## References
+
+- [GraphQL Field-Level Authorization](https://www.apollographql.com/docs/apollo-server/security/authentication/#authorization-in-resolvers)
+- [Caching Best Practices](https://redis.io/docs/manual/patterns/caching/)
+- [LRU Cache Implementation](https://www.npmjs.com/package/lru-cache)
+
+## Approval
+
+**Status**: Implemented  
+**Date**: December 10, 2025
+
+**Notes:**
+[See here for demo](https://github.com/jason-t-hankins/Social-Feed/)
\ No newline at end of file
diff --git a/apps/docs/docs/decisions/0027-client-side-caching.md b/apps/docs/docs/decisions/0027-client-side-caching.md
new file mode 100644
index 000000000..8133409a5
--- /dev/null
+++ b/apps/docs/docs/decisions/0027-client-side-caching.md
@@ -0,0 +1,305 @@
+# Client-Side Caching with Apollo Client
+
+## Context and Problem Statement
+
+Client-side caching is critical for responsive UX and reducing server load. Apollo Client provides a normalized cache, but developers need guidance on:
+
+- Cache policy selection (cache-first, network-only, cache-and-network)
+- Security: preventing sensitive data exposure in cache
+- Varying field selections: how Apollo merges queries with different fields
+- Cache invalidation strategies
+- Effective use of Apollo DevTools
+
+This ADR provides patterns for client-side caching with emphasis on security and field-level access control.
+
+**Live Demo**: `client/src/demos/05-client-cache/ClientCacheDemo.tsx`
+
+## Decision Drivers
+
+- Performance: Minimize network requests and server load
+- Security: Never expose sensitive data in client cache
+- User Experience: Instant UI updates with optimistic responses
+- Data Freshness: Balance caching with real-time requirements
+- Developer Experience: Clear patterns that scale with team size
+
+## Considered Options
+
+### Apollo Client vs Alternatives
+
+Evaluated: Apollo Client, TanStack Query, SWR, Redux RTK Query
+
+**Apollo Client chosen for**:
+- Automatic normalization (User:123 cached once, shared across queries)
+- GraphQL-first with fragments, type policies, subscriptions
+- Field policies for data transformation/masking
+- Excellent DevTools
+
+**Trade-offs**:
+- Bundle size: 33 KB vs 5-13 KB for alternatives
+- Learning curve: normalization and cache keys
+- GraphQL-only (can't cache REST easily)
+
+**Rationale**: For GraphQL projects with complex data relationships, Apollo's normalized cache and GraphQL-specific features provide best DX and performance.
+
+### Cache Policies
+
+Apollo Client offers multiple fetch policies:
+
+#### cache-first (Default)
+Read from cache, fetch on cache miss. Best for static/public data.
+
+```typescript
+useQuery(GET_PRODUCT_CATALOG, { fetchPolicy: 'cache-first' });
+```
+
+Use cases: Product catalogs, blog posts, reference data
+
+#### network-only
+Always fetch fresh, appropriate for sensitive data.
+
+```typescript
+useQuery(GET_BANK_BALANCE, { fetchPolicy: 'network-only' });
+```
+
+Use cases: Bank balances, private messages, real-time data
+
+#### cache-and-network
+Show cached instantly, refresh in background.
+
+```typescript
+useQuery(GET_USER_FEED, { fetchPolicy: 'cache-and-network' });
+```
+
+Use cases: Social feeds, dashboards
+
+#### no-cache
+Bypasses cache entirely for single-use data.
+
+```typescript
+useQuery(GET_OTP, { fetchPolicy: 'no-cache' });
+```
+
+Use cases: OTP codes, reset tokens
+
+### Field-Level Security
+
+Use field policies to mask sensitive data:
+
+```typescript
+const cache = new InMemoryCache({
+  typePolicies: {
+    User: {
+      fields: {
+        ssn: {
+          read() {
+            return '***-**-****'; // Always masked
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+Benefits: Defense-in-depth, cache inspector safety, redacted logs
+
+### Varying Field Selections
+
+Apollo merges queries with different fields into same cache entry.
+
+Query minimal fields first, then full profile:
+- Minimal query caches 3 fields
+- Full query merges 6 fields total
+- Subsequent minimal queries read all 6 from cache
+
+Key insight: Query broader fields first, narrower queries benefit from cache.
+
+### useFragment for Cache Reads
+
+Read cached data without network request:
+
+```typescript
+function PostCard({ id }: { id: string }) {
+  const { complete, data } = useFragment({
+    fragment: POST_CARD_FRAGMENT,
+    from: { __typename: 'Post', id },
+  });
+
+  if (!complete) return null;
+  return <div>{data.content}</div>;
+}
+```
+
+Benefits: Zero network overhead, live updates, avoids prop drilling
+
+See ADR 0001 for re-render optimization details.
+
+### Optimistic Updates
+
+Update UI instantly before server confirms:
+
+```typescript
+const [likePost] = useMutation(LIKE_POST, {
+  optimisticResponse: {
+    likePost: { __typename: 'Post', id: postId, likeCount: currentLikeCount + 1 },
+  },
+});
+```
+
+Flow: UI updates instantly, mutation sent to server, Apollo auto-rolls back on failure.
+
+Use cases: Likes, favorites, toggles
+
+## Decision Outcome
+
+Adopt tiered caching strategy based on data sensitivity:
+
+### Tier 1: Public/Static - cache-first
+Product catalogs, blog posts, reference data
+
+### Tier 2: User-Specific - cache-and-network
+Social feeds, shopping carts, dashboards
+
+### Tier 3: Sensitive - network-only
+Account balances, private messages, financial data
+
+### Tier 4: Highly Sensitive - no-cache
+Passwords, credit cards, OTP codes, SSNs
+
+### Field-Level Policies
+Always mask: User.ssn, User.creditCard (even if server sends real data)
+
+### Optimistic Updates
+Use for: Likes, follows, toggles
+Avoid for: Complex validation, transactions, unpredictable side effects
+
+## Implementation
+
+### Configure Cache
+
+```typescript
+const cache = new InMemoryCache({
+  typePolicies: {
+    User: {
+      keyFields: ['id'],
+      fields: {
+        ssn: { read() { return '***-**-****'; } },
+      },
+    },
+  },
+});
+```
+
+### Use Appropriate Policies
+
+```typescript
+// Public data
+useQuery(GET_PRODUCTS, { fetchPolicy: 'cache-first' });
+
+// Sensitive data
+useQuery(GET_BALANCE, { fetchPolicy: 'network-only' });
+
+// User feeds
+useQuery(GET_FEED, { fetchPolicy: 'cache-and-network' });
+```
+
+## Cache Invalidation
+
+### Refetch Queries
+```typescript
+useMutation(UPDATE_POST, {
+  refetchQueries: ['GetFeed'],
+});
+```
+
+### Cache Eviction
+```typescript
+useMutation(DELETE_POST, {
+  update(cache) {
+    cache.evict({ id: cache.identify({ __typename: 'Post', id: postId }) });
+    cache.gc();
+  },
+});
+```
+
+### Polling (use sparingly)
+```typescript
+useQuery(GET_NOTIFICATIONS, { pollInterval: 5000 });
+```
+
+## Tooling and Debugging
+
+### Apollo DevTools
+Chrome/Firefox extension for cache inspection, query tracking, mutation debugging
+
+### Browser Network Tab
+Filter by `graphql` to verify cache behavior:
+- cache-first: no network request after first fetch
+- network-only: always hits network
+
+### Cache Debugging
+```typescript
+console.log(client.cache.extract()); // View entire cache
+```
+
+## Considerations
+
+### Memory Usage
+Large caches consume client memory. Target: 10-50 MB for most apps.
+Mitigation: Run cache.gc() periodically, evict old entries.
+
+### Stale Data
+Cached data becomes outdated. Use cache-and-network for frequently changing data, mutation-based invalidation.
+
+### Privacy
+Clear cache on logout: `client.clearStore()`
+Use network-only for sensitive data on shared devices.
+
+### Multi-Tab Consistency
+Separate caches per tab. Use BroadcastChannel API or polling for sync.
+
+## Example Scenarios
+
+### E-Commerce
+- Product info: cache-first
+- Reviews: cache-and-network
+- Inventory: network-only with polling
+
+### Social Feed
+- Feed: cache-and-network
+- Likes: Optimistic updates
+
+### Banking
+- Balance: network-only
+- Transactions: cache-and-network
+- Profile: cache-first
+
+## Consequences
+
+### Positive
+- Instant UI for cached data, reduced server load
+- Field policies prevent sensitive data exposure
+- Optimistic updates provide instant feedback
+- Apollo DevTools enable effective debugging
+
+### Negative
+- Requires understanding normalization and cache keys
+- Aggressive caching risks stale data
+- Large caches consume client memory
+- Cache issues can be subtle to debug
+
+### Neutral
+- Team training required for cache policies
+- Periodic review needed as app evolves
+
+## Related
+
+- ADR 0001: useFragment for cache reads without queries
+- ADR 0003: Server-side permission-aware caching
+- DataLoader optimizes database, client cache optimizes network
+
+## References
+
+- [Apollo Client Caching](https://www.apollographql.com/docs/react/caching/overview/)
+- [Fetch Policies](https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy)
+- [Apollo DevTools](https://www.apollographql.com/docs/react/development-testing/developer-tooling/#apollo-client-devtools)

From a3b0753421523c287daa3a038c708ec2e0650267 Mon Sep 17 00:00:00 2001
From: Jason Hankins <jason.hankins27@gmail.com>
Date: Fri, 12 Dec 2025 11:53:18 -0500
Subject: [PATCH 02/10] condense wordy ADRs and follow template

---
 ...024-usefragment-vs-httpbatch-dataloader.md | 325 ++++++------------
 .../decisions/0025-public-graphql-caching.md  | 191 ++--------
 .../0026-permission-aware-caching.md          | 142 ++------
 .../decisions/0027-client-side-caching.md     | 141 +++-----
 4 files changed, 211 insertions(+), 588 deletions(-)

diff --git a/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md b/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
index 19b73419b..ca7dba382 100644
--- a/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
+++ b/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
@@ -1,59 +1,65 @@
 
-# useFragment vs HTTP Batch + DataLoader for GraphQL Optimization
+---
+sidebar_position: 24
+sidebar_label: 0024 GraphQL Optimization Patterns
+description: "Decision record for useFragment, HTTP batching, and DataLoader"
+status: 
+contact: jason-t-hankins
+date: 2025-12-12
+deciders: 
+consulted: 
+informed:
+---
+
+# GraphQL Performance Optimization with useFragment, HTTP Batching, and DataLoader
 
 ## Context and Problem Statement
 
-The Social-Feed project demonstrates GraphQL optimization patterns for production applications. We need clear, research-backed guidance on when to use:
-- **useFragment** (Apollo Client) for creating lightweight live bindings to cache data
-- **HTTP Batching** (Apollo Client) for reducing network overhead  
-- **DataLoader** (Server-side) for solving N+1 database queries
+ShareThrift's GraphQL API serves user profiles, event listings, community feeds, and real-time notifications. As the platform scales, we need clear guidance on when to apply Apollo Client and server-side optimization patterns:
+- **useFragment** - Creating lightweight cache bindings to eliminate unnecessary re-renders
+- **HTTP Batching** - Reducing network overhead by combining multiple operations
+- **DataLoader** - Solving N+1 database queries for MongoDB aggregations
 
-These patterns optimize different layers of the stack and complement each other.
+These patterns optimize different layers and work together to improve performance at scale.
 
-## DataLoader (Database Enhancement)
+## DataLoader - Database Query Batching
 
-**DataLoader solves the N+1 query problem and is ALWAYS required in production.**
+DataLoader solves the N+1 query problem by batching and caching database requests within a single GraphQL operation.
 
-### Performance Impact Example in the Sample App
-- **10 posts**: 11 queries → 2 queries (82% faster)
-- **1000 posts**: 3,001 queries → 4 queries (99.9% reduction)
+**Impact for ShareThrift:**
+- Event feed with 50 items + creator profiles: 51 MongoDB queries → 2 queries
+- User search with 20 results + membership data: 21 queries → 2 queries
+- Community page with 100 members + user profiles: 101 queries → 2 queries
 
-### Why It's Necessary
-Without DataLoader, every relationship traversal triggers a separate database query. With 10 posts each having an author, you execute 1 query for posts + 10 queries for authors = 11 total. DataLoader batches those 10 author queries into 1 query.
+Without DataLoader, each relationship traversal triggers a separate database query. With 10 events each having a creator, you'd execute 1 query for events + 10 queries for creators = 11 total. DataLoader automatically batches those 10 creator queries into 1.
 
-**Conclusion:** DataLoader should be enabled for GraphQL operations.
+## HTTP Batching - Network Request Consolidation
 
-## HTTP Batching (Network Optimization)
+HTTP Batching combines multiple GraphQL operations into a single HTTP request, reducing network overhead.
 
-**HTTP Batching combines multiple GraphQL operations into a single HTTP request, reducing network overhead.**
+**Impact for ShareThrift:**
+- Dashboard loading (user profile + notifications + events): 3 HTTP requests → 1 batched request
+- Event detail page (event + comments + creator + attendees): 4 requests → 1 request
+- Particularly valuable for mobile users on high-latency networks
 
-### Performance Impact Example in the Sample App
-- **5 simultaneous queries**: 5 HTTP requests → 1 batched request (40-60% faster)
-- Eliminates redundant connection setup, headers, and SSL handshakes
-- Most beneficial on HTTP/1.1 and high-latency networks
+When multiple React components independently fetch data, each triggers a separate HTTP request. HTTP Batching waits 20ms to collect operations and sends them together, eliminating redundant connection setup, headers, and SSL handshakes.
 
-### Why It's Useful
-When multiple components independently fetch data (common in dashboards), each triggers a separate HTTP request. HTTP Batching waits 20ms to collect operations and sends them together. Example: Loading a dashboard with user profile + notifications + messages = 3 requests becomes 1 request.
+## useFragment + @nonreactive - Re-Render Optimization
 
-**Conclusion:** HTTP Batching should be considered for UIs with multiple simultaneous queries.
+This pattern enables surgical cache updates and eliminates unnecessary re-renders, particularly valuable for list rendering.
 
-## useFragment (Client-side Optimization)
+**Impact for ShareThrift:**
+- Event feed with 50 items: Updates to one event (like count, attendance) don't re-render the entire feed
+- Community member list with 100 users: Profile updates only re-render affected member cards
+- Notification list: New notifications don't trigger re-renders of existing items
 
-**useFragment + @nonreactive enables surgical cache updates and eliminates unnecessary re-renders, particularly powerful for rendering lists.**
+**Key Benefits:**
+- Pass only cache keys (IDs) as props instead of full data objects
+- Components read directly from cache without parent re-renders
+- Each list item subscribes only to its own cache data
+- Updates to one item don't cascade to siblings or parents
 
-### Performance Impact
-- **Targeted cache reads**: Pass only cache keys (IDs) as props instead of full data objects
-- **Direct cache subscriptions**: Leaf components read directly from cache without parent re-renders
-- **List rendering optimization**: Each list item subscribes only to its own cache data
-- **Waterfall elimination**: Updates to one item don't trigger re-renders of siblings or parents
-
-### Why It's Useful
-- **Initial render speed**: Nearly identical to props-based approach
-- **Network performance**: No difference - same GraphQL queries
-- **Primary benefit**: Eliminating **unnecessary re-renders**, not faster execution
-- **Organization**: Architectural pattern allows reusability
-
-**Conclusion:** useFragment + @nonreactive should be used for list rendering and scenarios where you need fine-grained control over what re-renders when cache updates occur. It's not a speed optimization - it's a **re-render reduction** optimization that provides massive benefits at scale.
+This isn't a speed optimization - it's a re-render reduction pattern that prevents performance degradation at scale.
 
 ## Decision Drivers
 
@@ -79,15 +85,13 @@ Use basic Apollo Client/Server without optimization patterns.
 
 ## Decision Outcome
 
-**Chosen option: "Option 1 - Use All Three Patterns"**
+Chosen option: **Use all three patterns** - DataLoader, HTTP Batching, and useFragment + @nonreactive.
 
 ### Rationale
 
-Based on research from Apollo GraphQL documentation and the test results from the Social-Feed sample app:
-
-1. **DataLoader should always be used** for any GraphQL server in production. The N+1 problem is universal and devastating to performance without batching.
+**DataLoader** is non-negotiable for production GraphQL servers. The N+1 problem is universal across MongoDB aggregations and relationship traversals.
 
-2. **useFragment + @nonreactive + Fragment Colocation** provides specific benefits:
+**useFragment + @nonreactive** provides specific benefits for ShareThrift's list-heavy UI:
    
    **Primary Benefits** (Re-Render Reduction):
    - **Surgical cache updates**: Update one item = only that component re-renders (91-99% re-render reduction)
@@ -113,8 +117,8 @@ Based on research from Apollo GraphQL documentation and the test results from th
    - Most benefit comes from **avoiding re-render waterfalls**, not faster execution
    - Consider `useBackgroundQuery` for actual perceived performance improvements
 
-3. **HTTP Batching is scenario-dependent** but valuable for:
-   - HTTP/1.1 connections (still majority of mobile traffic)
+**HTTP Batching** is valuable for ShareThrift's dashboard and multi-component pages:
+   - HTTP/1.1 connections (majority of mobile traffic)
    - High-latency networks
    - Dashboard-style UIs with 10+ independent queries executing simultaneously
    - **Research**: Cloudflare study shows 35-50% improvement in multi-query scenarios
@@ -123,31 +127,28 @@ Based on research from Apollo GraphQL documentation and the test results from th
    - HTTP Batching does not provide improvement on static web pages or sites with minimal queries.
    - Large batchIntervals and small batchIntervals will have linear effects on the performance depending on the number of simultaneous requests. (If you have a large batch and a small number of requests, you may end up waiting longer than necessary)
 
-### Implementation Details
+### Implementation for ShareThrift
 
-**DataLoader** (Server):
+**DataLoader (Server):**
 ```typescript
-// ALWAYS implement - no exceptions
 const loaders = {
   userLoader: new DataLoader(batchLoadUsers),
-  commentCountLoader: new DataLoader(batchLoadCommentCounts),
-  // ... all related entity loaders
+  eventLoader: new DataLoader(batchLoadEvents),
+  communityLoader: new DataLoader(batchLoadCommunities),
 };
 ```
 
-**HTTP Batching** (Client):
+**HTTP Batching (Client):**
 ```typescript
-// Enable with environment flag for A/B testing
 const batchLink = new BatchHttpLink({
   uri: '/graphql',
   batchMax: 10,
-  batchInterval: 20, // 20ms batching window
+  batchInterval: 20,
 });
 ```
 
-**Fragment Colocation** (Client):
+**Fragment Colocation (Client):**
 ```typescript
-// Each component declares its own data needs
 const USER_AVATAR_FRAGMENT = gql`
   fragment UserAvatarData on User {
     displayName
@@ -156,16 +157,14 @@ const USER_AVATAR_FRAGMENT = gql`
 `;
 
 function UserAvatar({ user }) {
-  // Component is self-contained and portable
   return <img src={user.avatarUrl} alt={user.displayName} />;
 }
 
-// Parent query automatically includes nested fragments
-const GET_POST = gql`
-  query GetPost {
-    post {
-      author {
-        ...UserAvatarData  # Automatic!
+const GET_EVENT = gql`
+  query GetEvent {
+    event {
+      creator {
+        ...UserAvatarData
       }
     }
   }
@@ -173,90 +172,53 @@ const GET_POST = gql`
 `;
 ```
 
-**useFragment + @nonreactive Pattern** (Client):
+**useFragment + @nonreactive Pattern (Client):**
 ```typescript
-// Step 1: Parent query uses @nonreactive on the fragment
-const GET_POSTS_QUERY = gql`
-  query GetPosts {
-    feed {
-      edges {
-        node {
-          id                        # Parent watches IDs (add/remove items)
-          ...PostCardData @nonreactive  # But NOT data field changes!
-        }
-      }
+// Parent query with @nonreactive
+const GET_EVENTS_QUERY = gql`
+  query GetEvents {
+    events {
+      id
+      ...EventCardData @nonreactive
     }
   }
-  ${POST_CARD_FRAGMENT}
+  ${EVENT_CARD_FRAGMENT}
 `;
 
-// Parent component - render count stays at 1!
-function Feed() {
-  const { data } = useQuery(GET_POSTS_QUERY);
-  const postIds = data.feed.edges.map(edge => edge.node.id);
-  
-  return postIds.map(id => <PostCard key={id} postId={id} />);
-  // Parent only re-renders when IDs change (items added/removed)
-  // Updates to post data (likes, content) DON'T trigger parent re-render
+// Parent only re-renders when IDs change (events added/removed)
+function EventFeed() {
+  const { data } = useQuery(GET_EVENTS_QUERY);
+  const eventIds = data.events.map(event => event.id);
+  return eventIds.map(id => <EventCard key={id} eventId={id} />);
 }
 
-// Step 2: Child uses useFragment with only ID prop
-function PostCard({ postId }) {
+// Child reads from cache - only re-renders when THIS event changes
+function EventCard({ eventId }) {
   const { data } = useFragment({
-    fragment: POST_CARD_FRAGMENT,
-    from: { __typename: 'Post', id: postId },
+    fragment: EVENT_CARD_FRAGMENT,
+    from: { __typename: 'Event', id: eventId },
   });
   
-  // Direct cache subscription - this component re-renders ONLY when THIS post changes
-  // Parent doesn't re-render, siblings don't re-render
-  // Result: Click "like" on post #5 = only post #5 re-renders!
   return (
     <div>
       <h3>{data.title}</h3>
-      <button onClick={() => incrementLikes(postId)}>
-        ❤️ {data.likeCount}
+      <button onClick={() => toggleAttendance(eventId)}>
+        {data.isAttending ? 'Attending' : 'Join'}
       </button>
     </div>
   );
 }
 ```
 
-## Consequences
-
-### Good
-
-1. **Dramatic Performance Improvements** (Research-Backed)
-   - Database queries: 450 → 8 queries (98% improvement) via DataLoader - Shopify case study
-   - Network requests: 10 → 1 request (90% reduction) via HTTP Batching - Dashboard scenarios
-   - Initial load time: 3.2s → 1.1s (66% improvement) - Combined optimizations
-
-2. **Developer Experience**
-   - Fragment colocation reduces breaking changes by 70% in large teams (Shopify Engineering)
-   - Components become portable and self-documenting
-   - Self-documenting components (data requirements visible)
-   - Easier testing and debugging
-
-3. **Production-Ready Architecture**
-   - Aligns with Apollo and industry best practices
-   - Scales to millions of users (pattern used in companies like Shopify)
-   - Supports real-time features efficiently
-
-### Bad
+### Consequences
 
-1. **Learning Curve**
-   - Team needs training on all three patterns
-   - More complex than basic Apollo Client/Server setup
-   - Fragment composition requires understanding of cache normalization
-
-2. **Debugging Complexity**
-   - More layers to troubleshoot
-   - Batching can obscure individual operation performance
-   - Cache invalidation requires careful management
-
-3. **Maintenance Overhead**
-   - DataLoaders must be per-request (security requirement)
-   - Fragment updates require coordinated changes
-   - HTTP batching configuration needs tuning
+- Good, because database queries reduced by 95%+ for relationship-heavy pages
+- Good, because network request consolidation improves mobile user experience
+- Good, because re-render optimization prevents performance degradation on large lists
+- Good, because fragment colocation makes components portable and self-documenting
+- Bad, because team must learn cache normalization and fragment composition
+- Bad, because DataLoaders must be recreated per-request for security
+- Bad, because HTTP batching adds 20ms collection delay
 
 ## Validation
 
@@ -284,83 +246,16 @@ Created test pages to validate each pattern:
 
 
 
-### Validation
-
-1. **Code Review**: All new features must follow fragment colocation pattern
-2. **Performance Monitoring**: Track query counts and response times
-3. **Developer Onboarding**: Include optimization patterns in training
-4. **Quarterly Review**: Reassess patterns based on production metrics
-
-## Pros and Cons of the Options
-
-### Option 1: Use All Three Patterns
-
-**Pros:**
-- Maximum performance at all layers (network, cache, database)
-- Industry-proven approach (Apollo, Shopify, Netflix, GitHub)
-- Measurable improvements: 66-98% in various metrics
-- Future-proof architecture supporting real-time features
-- Best developer experience with fragment colocation
-
-**Cons:**
-- Highest initial complexity and learning curve
-- Most maintenance overhead
-- Requires team training and discipline
-
-**Evidence:**
-- Apollo DevRel: "This is the recommended production architecture"
-- Shopify: 85% query time improvement with full stack
-- Our testing: Confirmed benefits across all three dimensions
-
-### Option 2: Server-Side Only (DataLoader)
-
-**Pros:**
-- Solves most critical problem (N+1)
-- Simpler than full stack
-- Server-side focus easier to implement
-
-**Cons:**
-- Misses client-side optimization opportunities
-- Still hit by HTTP overhead and re-render issues
-- Not aligned with Apollo best practices for complex UIs
-
-**Evidence:**
-- Leaves 35-50% performance on table (HTTP batching)
-- Shopify: Fragment colocation provided 30% maintainability improvement
-
-### Option 3: Client-Side Only
-
-**Pros:**
-- Better user experience (faster rendering)
-- Fewer HTTP requests
-
-**Cons:**
-- **Critical flaw**: Doesn't solve N+1 problem
-- Will hit database scalability limits
-- Not viable for production
-
-**Evidence:**
-- Apollo: "DataLoader is non-negotiable for production GraphQL servers"
-- Without DataLoader: 450+ database queries for simple feed view
-
-### Option 4: Minimal (No Optimizations)
-
-**Pros:**
-- Simplest implementation
-- Fastest initial development
-
-**Cons:**
-- **Not production-ready**
-- Poor performance at scale
-- Will require rewrite when issues emerge
-
-**Evidence:**
-- sample app tests: 11x more database queries without DataLoader
-- 10x more HTTP requests without batching
-- Excessive re-renders without useFragment
+## More Information
 
 ## More Information
 
+- [Social-Feed Demo Application](https://github.com/jason-t-hankins/Social-Feed/)
+- [Apollo GraphQL Documentation](https://www.apollographql.com/docs/)
+- [DataLoader GitHub Repository](https://github.com/graphql/dataloader)
+- [Shopify Engineering: Solving N+1 Problem](https://shopify.engineering/solving-the-n-1-problem-for-graphql-through-batching)
+- [Apollo Client useFragment Discussion](https://github.com/apollographql/apollo-client/issues/11118)
+
 ### Automatic Persisted Queries (APQ) Compatibility
 
 APQ sends query hashes instead of full query strings to reduce request size.
@@ -369,35 +264,7 @@ APQ sends query hashes instead of full query strings to reduce request size.
 
 **Key Trade-off:** Choose between HTTP Batching (POST) OR CDN Caching (GET) - cannot use both simultaneously.
 
-- **Our demo uses POST** (default) - fully APQ-compatible
+- **ShareThrift uses POST** (default) - fully APQ-compatible
 - **GET mode** (`useGETForHashedQueries: true`) enables CDN caching but disables batching
 - **Production choice:** Dashboard/admin = batching (POST), Public content = CDN (GET)
 
-### External Resources
-
-- Apollo GraphQL Docs: https://www.apollographql.com/docs/
-- DataLoader: https://github.com/graphql/dataloader
-- Shopify Engineering: https://shopify.engineering/solving-the-n-1-problem-for-graphql-through-batching
-- useFragment Performance Discussion: https://github.com/apollographql/apollo-client/issues/11118
-
-### When to Revisit
-
-1. **Apollo Client Major Version**: New optimization features may change recommendations
-2. **HTTP/3 Adoption**: May reduce HTTP batching benefits
-3. **Team Feedback**: If patterns prove too complex in practice
-4. **Production Metrics**: If A/B tests show different results than research
-
-### Decision Date
-
-- **Initial Decision**: December 2025
-- **Next Review**: March 2026 (after production deployment)
-- **Responsible**: Engineering Team Lead
-
-### Approval
-
-This ADR represents the recommended approach based on:
-- Industry research and best practices
-- Apollo GraphQL official guidance
-- Internal testing and validation
-- Production requirements
-
diff --git a/apps/docs/docs/decisions/0025-public-graphql-caching.md b/apps/docs/docs/decisions/0025-public-graphql-caching.md
index 8bbc40325..d985643fa 100644
--- a/apps/docs/docs/decisions/0025-public-graphql-caching.md
+++ b/apps/docs/docs/decisions/0025-public-graphql-caching.md
@@ -1,15 +1,27 @@
+---
+sidebar_position: 25
+sidebar_label: 0025 Public GraphQL Caching
+description: "Decision record for public GraphQL caching with CDN support"
+status:
+contact: jason-t-hankins
+date: 2025-12-12
+deciders: 
+consulted: 
+informed:
+---
+
 # Public GraphQL Caching for CDN and Network Providers
 
 ## Context and Problem Statement
 
-Many GraphQL applications serve both authenticated (private) and unauthenticated (public) content. Public content could benefit from caching by CDNs (Cloudflare, Fastly) and network providers (ISPs like Comcast), but traditional GraphQL implementations pose challenges:
+ShareThrift serves both authenticated users (managing events, communities, memberships) and unauthenticated visitors (browsing public event listings, viewing community pages). Public content could benefit from CDN caching (Cloudflare, Fastly) and network provider caching, but GraphQL's default behavior creates challenges:
 
-1. **JWT tokens in requests**: Authentication headers prevent public caching
-2. **POST requests**: GraphQL typically uses POST, which CDNs don't cache by default
-3. **Query size**: Full query strings in requests increase bandwidth
-4. **Token leakage risk**: Accidentally caching authenticated requests exposes sensitive data
+1. JWT tokens in requests prevent public caching
+2. POST requests aren't cached by CDNs by default
+3. Full query strings increase bandwidth consumption
+4. Risk of accidentally caching authenticated data and exposing sensitive information
 
-**Goal**: Develop actionable guidance for enabling public (shared) caching of unauthenticated GraphQL queries while maintaining security and performance.
+We need guidance for enabling public caching of unauthenticated queries while maintaining security.
 
 ## Decision Drivers
 
@@ -37,28 +49,15 @@ Continue with current approach - all queries authenticated, no public caching.
 
 ## Decision Outcome
 
-**Recommended Option: "Option 1 - Separate Endpoints"**
-
-### Rationale
+Chosen option: **Separate endpoints** - `/graphql` for authenticated requests and `/graphql-public` for public requests.
 
-1. **Security**: Physical separation eliminates token leakage risk
-   - Public endpoint never sees Authorization headers
-   - Impossible to accidentally cache authenticated requests
-   - Clear audit trail for public vs private access
+**Security**: Physical separation eliminates token leakage risk. Public endpoint never sees Authorization headers.
 
-2. **Performance**: Optimized for each use case
-   - Public: GET requests + APQ + HTTP caching
-   - Authenticated: POST + HTTP batching + DataLoader
+**Performance**: Each endpoint optimized for its use case - public uses GET requests with APQ and HTTP caching, authenticated uses POST with HTTP batching and DataLoader.
 
-3. **Compatibility**: Standard HTTP caching
-   - No custom CDN configuration needed
-   - Works with any HTTP cache (CDN, ISP, browser)
-   - Standard Cache-Control headers
+**Compatibility**: Standard HTTP caching works with any CDN without custom configuration.
 
-4. **Maintainability**: Clear boundaries
-   - Public queries explicitly defined in separate schema subset
-   - No ambiguity about what can be cached
-   - Easy to audit and validate
+**Maintainability**: Clear boundaries make public queries easy to audit and validate.
 
 ## Implementation Details
 
@@ -278,52 +277,24 @@ Apollo Server supports APQ out-of-the-box (enabled by default).
    - Risk of confusion about which client to use
    - Testing requires validating both endpoints
 
-## Recommendations for ShareThrift
+## ShareThrift Query Classification
 
 | Query | Public? | Reason |
 |-------|---------|--------|
 | `userById()` | ✅ Yes | Should be able to see users pages, specifics may be blocked |
-| `accountPlans()` | ✅ Yes | users signing up arent authenticated yet |
+| `accountPlans()` | ✅ Yes | Shown to unauthenticated users during signup |
 | `currentUser()` | ❌ No | requires authentication and could cause errors |
 | `adminUserById()` | ❌ No | specific calls like this could leak sensitive info |
 
-## Security Checklist
-
-Before enabling public caching:
-
-- [ ] Audit all public queries for PII
-- [ ] Ensure JWT tokens never sent to public endpoint
-- [ ] Test with curl/Postman to verify no auth headers
-- [ ] Monitor logs for accidental auth header usage
-- [ ] Set up alerts for suspicious caching patterns
-- [ ] Document which queries are public vs private
-- [ ] Add tests to prevent auth queries on public endpoint
-- [ ] Configure CDN to strip any auth headers (defense in depth)
-
-
-## Pros and Cons of the Options
-
-### Option 1: Separate Endpoints
-
-**Pros:**
-- Complete security isolation (no token leakage possible)
-- Optimized for each use case (caching vs batching)
-- Standard HTTP caching (works everywhere)
-- Clear boundaries (easy to audit)
-- Proven pattern (used by GitHub, Shopify)
+## More Information
 
-**Cons:**
-- Two endpoints to maintain
-- Two client configurations
-- Cannot use HTTP batching for public queries
-- More complex architecture
+- [Social-Feed Demo Application](https://github.com/jason-t-hankins/Social-Feed/)
+- [Apollo Server: Automatic Persisted Queries](https://www.apollographql.com/docs/apollo-server/performance/apq/)
+- [MDN: HTTP Caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching)
+- [GraphQL over HTTP Specification](https://graphql.github.io/graphql-over-http/)
+- [Cloudflare: CDN Caching Best Practices](https://www.cloudflare.com/learning/cdn/caching-best-practices/)
 
-**Evidence:**
-- Testing confirmed 97% faster cached responses
-- No auth headers detected in public requests
-- APQ working correctly with GET requests
-
-### Option 2: Same Endpoint with Conditional Auth
+### Alternative Approach: Same Endpoint with Conditional Auth
 
 This approach uses a single `/graphql` endpoint for both authenticated and public queries, with conditional logic to determine when to include authentication headers.
 
@@ -364,86 +335,7 @@ app.use('/graphql', expressMiddleware(server, {
 4. Server reads header and sets cache policy accordingly
 5. Apollo Server plugin applies correct `Cache-Control` headers
 
-**Pros:**
-- Single endpoint (simpler infrastructure)
-- One Apollo Server configuration
-- Can enable public caching without separate infrastructure
-
-**Cons:**
-- **Security Risk**: One misconfigured query exposes auth tokens to CDN
-- **Maintenance Burden**: Every query needs manual categorization in whitelist
-- **No Type Safety**: TypeScript can't enforce operation classification
-- **Coordination Required**: Client whitelist and server logic must stay in sync
-- **Complex Header Management**: Custom headers add another failure point
-- **Difficult to Audit**: Can't simply monitor one endpoint for auth headers
-- **CDN Configuration**: Still needs rules to respect custom headers
-- **Testing Complexity**: Must verify conditional logic for every operation
-- **Refactor Risk**: Renaming operations breaks whitelist silently
-- **Team Confusion**: Not obvious which queries are public from schema
-
-**Real-World Failure Scenarios:**
-1. Developer adds new query, forgets to add to whitelist → token cached by CDN
-2. Operation renamed during refactor → whitelist breaks, wrong auth behavior
-3. Custom header stripped by proxy/firewall → all requests treated as public
-4. Whitelist logic bug → tokens leaked to public cache
-5. New team member doesn't understand whitelist pattern → adds query incorrectly
-
-**Evidence:**
-- Implemented as alternative demo (ConditionalAuthDemo.tsx) showing the pattern
-- Rejected due to security and maintenance concerns
-- Industry consensus: physical separation is safer
-- Demo explicitly warns against this approach
-
-**Why Physical Separation is Better:**
-- **Impossible to leak tokens**: Public endpoint never receives auth headers
-- **Self-documenting**: Endpoint URL makes intent clear
-- **Easy to audit**: Simply monitor `/graphql-public` for ANY auth header (should be zero)
-- **No coordination needed**: No whitelist to maintain
-- **Fail-safe**: Misconfiguration doesn't expose tokens
-
-### Option 3: No Public Caching
-
-**Pros:**
-- Simplest implementation
-- No additional complexity
-
-**Cons:**
-- Misses major performance opportunity
-- Higher server costs
-- Worse user experience for public content
-
-**Evidence:**
-- Not viable for high-traffic public endpoints
-
-## References
-
-- [Apollo Client - Persisted Queries](https://www.apollographql.com/docs/apollo-server/performance/apq/)
-- [HTTP Caching - MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching)
-- [GraphQL over HTTP Spec](https://graphql.github.io/graphql-over-http/)
-- [CDN Caching Best Practices](https://www.cloudflare.com/learning/cdn/caching-best-practices/)
-
-## More Information
-
-### When to Use This Pattern
-
-**Ideal for:**
-- High-traffic public content (blog posts, product catalogs, news feeds)
-- APIs serving both authenticated and unauthenticated users
-- Applications with clear public/private data boundaries
-- Services targeting global audiences (edge caching benefits)
-
-**Not ideal for:**
-- Purely authenticated applications (no public content)
-- Real-time data requiring immediate consistency
-- Applications with mostly personalized content
-- Low-traffic services (overhead not worth complexity)
-
-### When to Revisit
-
-1. **HTTP/3 Adoption**: May change GET vs POST trade-offs
-2. **Apollo Client Updates**: New caching features may emerge
-3. **CDN Provider Changes**: Different providers may have different capabilities
-4. **Traffic Patterns**: If public traffic drops below 70%, pattern may not be worth it
+**Note:** This approach is not recommended due to security risks of misconfigured queries exposing tokens to CDN and the maintenance burden of maintaining operation whitelists.
 5. **Security Incidents**: Any token leakage would require immediate review
 
 ### Success Criteria
@@ -458,21 +350,4 @@ app.use('/graphql', expressMiddleware(server, {
 - [x] Clear documentation and examples (ADR, demo UI)
 - [x] Working demonstration of pattern (side-by-side comparison)
 
-**Nice to Have**:
-- [x] APQ working correctly (100% of public queries)
-- [x] Payload size reduction (90% with APQ)
-- [ ] Production CDN deployment for real-world validation
-
-### Approval
-
-This ADR represents the implemented approach based on:
-- Security requirements (no token leakage)
-- Performance testing (97% improvement confirmed)
-- Apollo GraphQL best practices
-- HTTP caching standards
-- Validation testing completed December 9, 2025
 
-**Status**: Implemented  
-**Date**: December 9, 2025  
-**Decision Makers**: Engineering Team  
-**Next Review**: After production deployment
diff --git a/apps/docs/docs/decisions/0026-permission-aware-caching.md b/apps/docs/docs/decisions/0026-permission-aware-caching.md
index 45806a0ac..6a1da5b6b 100644
--- a/apps/docs/docs/decisions/0026-permission-aware-caching.md
+++ b/apps/docs/docs/decisions/0026-permission-aware-caching.md
@@ -1,16 +1,22 @@
+---
+sidebar_position: 26
+sidebar_label: 0026 Permission-Aware Caching
+description: "Decision record for implementing permission-aware in-memory caching in ShareThrift's GraphQL API."
+status: 
+contact: jason-t-hankins
+date: 2025-12-12
+deciders: 
+consulted: 
+informed:
+---
+
 # Permission-Aware In-Memory Caching for GraphQL
 
 ## Context and Problem Statement
 
-GraphQL applications often serve data to users with varying permission levels. A naive server-side caching implementation could accidentally serve admin-only data to regular users, or vice versa, creating serious security vulnerabilities.
-
-**Challenge**: How do we implement efficient server-side caching while ensuring users only see data they're authorized to access?
+ShareThrift's GraphQL API serves data to users with different permission levels - regular members, community admins, and platform administrators. A naive server-side caching implementation could accidentally serve admin-only data to regular users, creating serious security vulnerabilities.
 
-**Example Scenario** (Social Feed):
-- Admin users can see post analytics (view counts, engagement rates, geographic data)
-- Regular users see the same posts but without analytics
-- Both query the same endpoint: `feed(first: 5)`
-- Without permission-aware caching, an admin's cached response could leak to a regular user
+For example, admin users viewing event analytics (attendance rates, revenue) and regular members viewing the same event listing must not share cached data. Without permission-aware caching, an admin's cached response could leak sensitive information to regular users.
 
 ## Decision Drivers
 
@@ -40,29 +46,15 @@ Create distinct queries for each permission level (e.g., `adminFeed`, `userFeed`
 
 ## Decision Outcome
 
-**Recommended Option: "Option 2 - Permission-Aware Cache Keys"**
+Chosen option: **Permission-aware cache keys** - Include user permissions in cache keys to ensure isolation between permission levels.
 
-### Rationale
+**Security**: Cache keys include query, variables, userId, role, and permissions. Example: `GetEvents::{"first":5}::alice::admin::[]` vs `GetEvents::{"first":5}::bob::member::[]`. Users cannot access cached data for other permission levels.
 
-1. **Security by Design**
-   - Impossible for users to access cached data for other permission levels
-   - Cache key includes: query + variables + userId + role + permissions
-   - Example: `GetFeed::{"first":5}::alice::admin::[]` vs `GetFeed::{"first":5}::bob::user::[]`
+**Efficiency**: Users with identical permissions share cache entries. 1000 regular members = 1 cache entry.
 
-2. **Field-Level Permissions**
-   - GraphQL resolvers check permissions before returning fields
-   - `Post.analytics` resolver: `if (user.role !== 'admin') return null;`
-   - Cache stores the filtered result, not raw database data
+**Field-Level Control**: GraphQL resolvers check permissions before returning fields, storing only filtered results in cache.
 
-3. **Memory Efficient**
-   - Users with identical permissions share cache entries
-   - 1000 regular users = 1 cache entry (not 1000)
-   - TTL-based expiration prevents unbounded growth
-
-4. **Standard GraphQL Patterns**
-   - Works with any GraphQL server (Apollo, Express GraphQL, etc.)
-   - No changes to client code required
-   - Compatible with DataLoader and other optimizations
+**Compatibility**: Works with Apollo Server, Express GraphQL, and existing DataLoader optimizations.
 
 ## Implementation Details
 
@@ -197,74 +189,16 @@ class PermissionAwareCache {
    - Easy to monitor cache efficiency by permission level
    - Clear audit trail of who accessed what
 
-### Bad
-
-1. **Memory Usage**
-   - One cache entry per unique permission set (admin, user, etc.)
-   - 10 roles × 100 queries = 1000 cache entries
-   - Must set reasonable `maxSize` and TTL
-
-2. **Cache Fragmentation**
-   - Small differences in permissions = separate cache entries
-   - User with `["read", "write"]` vs `["write", "read"]` = different keys
-   - Mitigated by sorting permissions array
-
-3. **Invalidation Complexity**
-   - Changing user permissions requires invalidating their entries
-   - Data changes may need to invalidate multiple permission levels
-   - Need careful invalidation strategy
-
-4. **Cold Cache Problem**
-   - First request for each permission level is always slow
-   - New users don't benefit from existing cache entries
-   - Mitigated by reasonable TTL (30-60s)
-
-## Alternative Approaches
-
-### Option 1: No Server-Side Caching
-
-**Pros:**
-- Simplest implementation
-- No security risks from caching
-- Always fresh data
-
-**Cons:**
-- Poor performance (every request hits database)
-- High server load
-- Wasted computation for identical queries
-
-### Option 3: Post-Fetch Filtering
-
-**Approach:** Cache full dataset, filter based on permissions before returning.
-
-**Pros:**
-- One cache entry for all users
-- Memory efficient
-
-**Cons:**
-- **Security Risk**: Sensitive data in cache memory (could leak via memory dump)
-- **Complexity**: Must carefully filter every field
-- **Performance**: Filtering overhead on every request
-
-### Option 4: Separate Queries Per Permission Level
-
-**Approach:** Define separate GraphQL queries for each role.
-
-```graphql
-type Query {
-  feedAdmin: [Post!]!    # Returns posts with analytics
-  feedUser: [Post!]!     # Returns posts without analytics
-}
-```
+### Consequences
 
-**Pros:**
-- Clear separation
-- Client explicitly chooses permission level
-
-**Cons:**
-- Schema bloat (multiply queries by number of roles)
-- Client must know about server-side roles
-- Doesn't scale to complex permissions
+- Good, because zero risk of permission leakage between users
+- Good, because reduces database queries by 70-90% for users with same permissions
+- Good, because cache lookups under 1ms vs 50-200ms database queries
+- Good, because supports complex permission models (RBAC, ABAC, custom)
+- Good, because cache hits and misses logged per role for monitoring
+- Bad, because one cache entry per unique permission set increases memory usage
+- Bad, because changing user permissions requires invalidating their cache entries
+- Bad, because first request for each permission level is always slow (cold cache)
 
 
 ## Trade-Offs
@@ -533,19 +467,9 @@ cache.invalidate(pattern) {
 - [ ] Log cache hits/misses per role
 - [ ] Test with different permission levels
 - [ ] Verify no data leakage between roles
-- [ ] Monitor memory usage in production
-- [ ] Document permission model for team
-
-## References
-
-- [GraphQL Field-Level Authorization](https://www.apollographql.com/docs/apollo-server/security/authentication/#authorization-in-resolvers)
-- [Caching Best Practices](https://redis.io/docs/manual/patterns/caching/)
-- [LRU Cache Implementation](https://www.npmjs.com/package/lru-cache)
-
-## Approval
-
-**Status**: Implemented  
-**Date**: December 10, 2025
+## More Information
 
-**Notes:**
-[See here for demo](https://github.com/jason-t-hankins/Social-Feed/)
\ No newline at end of file
+- [Social-Feed Demo Application](https://github.com/jason-t-hankins/Social-Feed/)
+- [Apollo Server: Field-Level Authorization](https://www.apollographql.com/docs/apollo-server/security/authentication/#authorization-in-resolvers)
+- [Redis: Caching Best Practices](https://redis.io/docs/manual/patterns/caching/)
+- [NPM: LRU Cache Implementation](https://www.npmjs.com/package/lru-cache)
\ No newline at end of file
diff --git a/apps/docs/docs/decisions/0027-client-side-caching.md b/apps/docs/docs/decisions/0027-client-side-caching.md
index 8133409a5..4641067fd 100644
--- a/apps/docs/docs/decisions/0027-client-side-caching.md
+++ b/apps/docs/docs/decisions/0027-client-side-caching.md
@@ -1,18 +1,27 @@
+---
+sidebar_position: 27
+sidebar_label: 0027 Client-Side Caching
+description: "Decision record for client-side caching strategies using Apollo Client"
+status: 
+contact: jason-t-hankins
+date: 2025-12-12
+deciders: 
+consulted: 
+informed:
+---
+
 # Client-Side Caching with Apollo Client
 
 ## Context and Problem Statement
 
-Client-side caching is critical for responsive UX and reducing server load. Apollo Client provides a normalized cache, but developers need guidance on:
+ShareThrift requires responsive UI and reduced server load through effective client-side caching. Apollo Client provides a normalized cache, but we need clear guidance on:
 
 - Cache policy selection (cache-first, network-only, cache-and-network)
-- Security: preventing sensitive data exposure in cache
-- Varying field selections: how Apollo merges queries with different fields
-- Cache invalidation strategies
-- Effective use of Apollo DevTools
-
-This ADR provides patterns for client-side caching with emphasis on security and field-level access control.
+- Security considerations for preventing sensitive data exposure in client cache
+- Cache invalidation strategies for mutations
+- Effective use of Apollo DevTools for debugging
 
-**Live Demo**: `client/src/demos/05-client-cache/ClientCacheDemo.tsx`
+This decision focuses on cache policy patterns with emphasis on security and data freshness requirements.
 
 ## Decision Drivers
 
@@ -152,55 +161,46 @@ Use cases: Likes, favorites, toggles
 
 ## Decision Outcome
 
-Adopt tiered caching strategy based on data sensitivity:
+Chosen option: **Tiered caching strategy** based on data sensitivity and freshness requirements.
 
-### Tier 1: Public/Static - cache-first
-Product catalogs, blog posts, reference data
+**Tier 1 - Public/Static (cache-first)**: Event listings, community pages, account plans
 
-### Tier 2: User-Specific - cache-and-network
-Social feeds, shopping carts, dashboards
+**Tier 2 - User-Specific (cache-and-network)**: User feeds, event attendance, notifications
 
-### Tier 3: Sensitive - network-only
-Account balances, private messages, financial data
+**Tier 3 - Sensitive (network-only)**: Payment information, admin data, private messages
 
-### Tier 4: Highly Sensitive - no-cache
-Passwords, credit cards, OTP codes, SSNs
+**Tier 4 - Highly Sensitive (no-cache)**: Passwords, credit cards, OTP codes
 
-### Field-Level Policies
-Always mask: User.ssn, User.creditCard (even if server sends real data)
+**Field-Level Policies**: Mask sensitive fields even if server sends real data (defense-in-depth)
 
-### Optimistic Updates
-Use for: Likes, follows, toggles
-Avoid for: Complex validation, transactions, unpredictable side effects
+**Optimistic Updates**: Use for likes, follows, attendance toggles. Avoid for complex validations and transactions.
 
-## Implementation
-
-### Configure Cache
+### Implementation for ShareThrift
 
+**Configure Cache:**
 ```typescript
 const cache = new InMemoryCache({
   typePolicies: {
     User: {
       keyFields: ['id'],
       fields: {
-        ssn: { read() { return '***-**-****'; } },
+        email: { read() { return '***@***.com'; } },
       },
     },
   },
 });
 ```
 
-### Use Appropriate Policies
-
+**Apply Policies:**
 ```typescript
-// Public data
-useQuery(GET_PRODUCTS, { fetchPolicy: 'cache-first' });
+// Public event listings
+useQuery(GET_PUBLIC_EVENTS, { fetchPolicy: 'cache-first' });
 
-// Sensitive data
-useQuery(GET_BALANCE, { fetchPolicy: 'network-only' });
+// User-specific feed
+useQuery(GET_MY_FEED, { fetchPolicy: 'cache-and-network' });
 
-// User feeds
-useQuery(GET_FEED, { fetchPolicy: 'cache-and-network' });
+// Payment information
+useQuery(GET_PAYMENT_METHODS, { fetchPolicy: 'network-only' });
 ```
 
 ## Cache Invalidation
@@ -242,64 +242,21 @@ Filter by `graphql` to verify cache behavior:
 console.log(client.cache.extract()); // View entire cache
 ```
 
-## Considerations
-
-### Memory Usage
-Large caches consume client memory. Target: 10-50 MB for most apps.
-Mitigation: Run cache.gc() periodically, evict old entries.
-
-### Stale Data
-Cached data becomes outdated. Use cache-and-network for frequently changing data, mutation-based invalidation.
-
-### Privacy
-Clear cache on logout: `client.clearStore()`
-Use network-only for sensitive data on shared devices.
-
-### Multi-Tab Consistency
-Separate caches per tab. Use BroadcastChannel API or polling for sync.
-
-## Example Scenarios
-
-### E-Commerce
-- Product info: cache-first
-- Reviews: cache-and-network
-- Inventory: network-only with polling
-
-### Social Feed
-- Feed: cache-and-network
-- Likes: Optimistic updates
-
-### Banking
-- Balance: network-only
-- Transactions: cache-and-network
-- Profile: cache-first
-
 ## Consequences
 
-### Positive
-- Instant UI for cached data, reduced server load
-- Field policies prevent sensitive data exposure
-- Optimistic updates provide instant feedback
-- Apollo DevTools enable effective debugging
-
-### Negative
-- Requires understanding normalization and cache keys
-- Aggressive caching risks stale data
-- Large caches consume client memory
-- Cache issues can be subtle to debug
-
-### Neutral
-- Team training required for cache policies
-- Periodic review needed as app evolves
-
-## Related
-
-- ADR 0001: useFragment for cache reads without queries
-- ADR 0003: Server-side permission-aware caching
-- DataLoader optimizes database, client cache optimizes network
-
-## References
-
-- [Apollo Client Caching](https://www.apollographql.com/docs/react/caching/overview/)
-- [Fetch Policies](https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy)
+- Good, because instant UI response for cached data reduces perceived latency
+- Good, because reduced server load lowers infrastructure costs
+- Good, because field policies prevent sensitive data exposure as defense-in-depth
+- Good, because optimistic updates provide immediate user feedback
+- Good, because Apollo DevTools enable effective cache debugging
+- Bad, because requires understanding cache normalization and key generation
+- Bad, because aggressive caching risks stale data without proper invalidation
+- Bad, because large caches consume client memory (target: 10-50 MB)
+- Bad, because cache issues can be subtle to debug
+
+## More Information
+
+- [Social-Feed Demo Application](https://github.com/jason-t-hankins/Social-Feed/)
+- [Apollo Client: Caching Overview](https://www.apollographql.com/docs/react/caching/overview/)
+- [Apollo Client: Fetch Policies](https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy)
 - [Apollo DevTools](https://www.apollographql.com/docs/react/development-testing/developer-tooling/#apollo-client-devtools)

From ed0ed8a95b7005e7c42057c6819d254a270516e8 Mon Sep 17 00:00:00 2001
From: Jason Hankins <jason.hankins27@gmail.com>
Date: Mon, 15 Dec 2025 09:35:19 -0500
Subject: [PATCH 03/10] resolve copilot/sourcery suggestions

---
 ...024-usefragment-vs-httpbatch-dataloader.md |  7 ++--
 .../decisions/0025-public-graphql-caching.md  | 34 ++++++-------------
 .../0026-permission-aware-caching.md          | 34 +------------------
 .../decisions/0027-client-side-caching.md     |  2 +-
 4 files changed, 15 insertions(+), 62 deletions(-)

diff --git a/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md b/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
index ca7dba382..df86a22f5 100644
--- a/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
+++ b/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
@@ -1,4 +1,3 @@
-
 ---
 sidebar_position: 24
 sidebar_label: 0024 GraphQL Optimization Patterns
@@ -226,12 +225,12 @@ function EventCard({ eventId }) {
 
 Created test pages to validate each pattern:
 
-1. **HTTP Batching Test** ([BatchingDemo.tsx](../../client/src/pages/BatchingDemo.tsx))
+1. **HTTP Batching Test** ([BatchingDemo.tsx](https://github.com/jason-t-hankins/Social-Feed/blob/main/client/src/demos/01-http-batching/BatchingDemo.tsx))
    - Compares batched vs non-batched requests
    - Measures total request time and HTTP request count
    - **Result**: 3-5 simultaneous queries show 40% improvement with batching
 
-2. **useFragment Test** ([FragmentDemo.tsx](../../client/src/pages/FragmentDemo.tsx))
+2. **useFragment Test** ([FragmentDemo.tsx](https://github.com/jason-t-hankins/Social-Feed/blob/main/client/src/demos/02-usefragment/FragmentDemo.tsx))
    - Side-by-side comparison: WITHOUT vs WITH useFragment + @nonreactive
    - 10-item list with like buttons on each post
    - **WITHOUT**: Clicking any button = 11 re-renders (parent + 10 children)
@@ -246,8 +245,6 @@ Created test pages to validate each pattern:
 
 
 
-## More Information
-
 ## More Information
 
 - [Social-Feed Demo Application](https://github.com/jason-t-hankins/Social-Feed/)
diff --git a/apps/docs/docs/decisions/0025-public-graphql-caching.md b/apps/docs/docs/decisions/0025-public-graphql-caching.md
index d985643fa..708f6e198 100644
--- a/apps/docs/docs/decisions/0025-public-graphql-caching.md
+++ b/apps/docs/docs/decisions/0025-public-graphql-caching.md
@@ -86,7 +86,7 @@ const server = new ApolloServer({
     },
   ],
   persistedQueries: { cache: undefined },
-  csrfPrevention: false, // Allow GET requests
+  csrfPrevention: false, // Allow GET requests, requires further security safeguards, headers, rate limiting, etc.
 });
 
 // Authenticated endpoint
@@ -281,18 +281,12 @@ Apollo Server supports APQ out-of-the-box (enabled by default).
 
 | Query | Public? | Reason |
 |-------|---------|--------|
-| `userById()` | ✅ Yes | Should be able to see users pages, specifics may be blocked |
-| `accountPlans()` | ✅ Yes | Shown to unauthenticated users during signup |
-| `currentUser()` | ❌ No | requires authentication and could cause errors |
-| `adminUserById()` | ❌ No | specific calls like this could leak sensitive info |
+| `userById()` |  Yes | Should be able to see users' pages, specifics may be blocked |
+| `accountPlans()` |  Yes | Shown to unauthenticated users during signup |
+| `currentUser()` |  No | requires authentication and could cause errors |
+| `adminUserById()` |  No | specific calls like this could leak sensitive info |
 
-## More Information
 
-- [Social-Feed Demo Application](https://github.com/jason-t-hankins/Social-Feed/)
-- [Apollo Server: Automatic Persisted Queries](https://www.apollographql.com/docs/apollo-server/performance/apq/)
-- [MDN: HTTP Caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching)
-- [GraphQL over HTTP Specification](https://graphql.github.io/graphql-over-http/)
-- [Cloudflare: CDN Caching Best Practices](https://www.cloudflare.com/learning/cdn/caching-best-practices/)
 
 ### Alternative Approach: Same Endpoint with Conditional Auth
 
@@ -336,18 +330,12 @@ app.use('/graphql', expressMiddleware(server, {
 5. Apollo Server plugin applies correct `Cache-Control` headers
 
 **Note:** This approach is not recommended due to security risks of misconfigured queries exposing tokens to CDN and the maintenance burden of maintaining operation whitelists.
-5. **Security Incidents**: Any token leakage would require immediate review
-
-### Success Criteria
 
-**Must Have** (All Achieved):
-- [x] No JWT tokens in public endpoint requests (validated)
-- [x] Browser caching working (disk cache confirmed)
-- [x] Zero security incidents (no token leakage detected)
-
-**Should Have** (All Achieved):
-- [x] Significant response time improvement (97% faster for cached requests)
-- [x] Clear documentation and examples (ADR, demo UI)
-- [x] Working demonstration of pattern (side-by-side comparison)
 
+## More Information
 
+- [Social-Feed Demo Application](https://github.com/jason-t-hankins/Social-Feed/)
+- [Apollo Server: Automatic Persisted Queries](https://www.apollographql.com/docs/apollo-server/performance/apq/)
+- [MDN: HTTP Caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching)
+- [GraphQL over HTTP Specification](https://graphql.github.io/graphql-over-http/)
+- [Cloudflare: CDN Caching Best Practices](https://www.cloudflare.com/learning/cdn/caching-best-practices/)
\ No newline at end of file
diff --git a/apps/docs/docs/decisions/0026-permission-aware-caching.md b/apps/docs/docs/decisions/0026-permission-aware-caching.md
index 6a1da5b6b..ddc4699d9 100644
--- a/apps/docs/docs/decisions/0026-permission-aware-caching.md
+++ b/apps/docs/docs/decisions/0026-permission-aware-caching.md
@@ -165,31 +165,8 @@ class PermissionAwareCache {
 }
 ```
 
-## Consequences
-
-### Good
-
-1. **Security Guarantees**
-   - Zero risk of permission leakage between users
-   - Each permission level has isolated cache entries
-   - Failed permission checks don't touch cache
-
-2. **Performance Benefits**
-   - Reduces database queries by 70-90% for identical permission sets
-   - Less than 1ms cache lookups vs 50-200ms database queries
-   - Users with same role share cached data
 
-3. **Flexibility**
-   - Supports complex permission models (RBAC, ABAC, custom)
-   - Fine-grained control per field
-   - Easy to add new permission checks without cache changes
-
-4. **Observable**
-   - Cache hits/misses logged per role
-   - Easy to monitor cache efficiency by permission level
-   - Clear audit trail of who accessed what
-
-### Consequences
+## Consequences
 
 - Good, because zero risk of permission leakage between users
 - Good, because reduces database queries by 70-90% for users with same permissions
@@ -457,16 +434,7 @@ cache.invalidate(pattern) {
 }
 ```
 
-## Implementation Checklist
 
-- [ ] Define cache key structure with permission context
-- [ ] Implement permission checks in resolvers BEFORE caching
-- [ ] Set reasonable `maxSize` (500-1000 entries)
-- [ ] Set appropriate TTL (30-60s for most data)
-- [ ] Add cache invalidation on mutations
-- [ ] Log cache hits/misses per role
-- [ ] Test with different permission levels
-- [ ] Verify no data leakage between roles
 ## More Information
 
 - [Social-Feed Demo Application](https://github.com/jason-t-hankins/Social-Feed/)
diff --git a/apps/docs/docs/decisions/0027-client-side-caching.md b/apps/docs/docs/decisions/0027-client-side-caching.md
index 4641067fd..6274734c8 100644
--- a/apps/docs/docs/decisions/0027-client-side-caching.md
+++ b/apps/docs/docs/decisions/0027-client-side-caching.md
@@ -141,7 +141,7 @@ function PostCard({ id }: { id: string }) {
 
 Benefits: Zero network overhead, live updates, avoids prop drilling
 
-See ADR 0001 for re-render optimization details.
+See ADR 0024 for re-render optimization details.
 
 ### Optimistic Updates
 

From e39f4c97ab5a98c3e5277a8d77af92e1af8804f2 Mon Sep 17 00:00:00 2001
From: Jason Hankins <jason.hankins27@gmail.com>
Date: Wed, 17 Dec 2025 10:06:40 -0500
Subject: [PATCH 04/10] Remove unnecessary code snippets, create diagrams

---
 ...024-usefragment-vs-httpbatch-dataloader.md | 146 +++----
 .../decisions/0025-public-graphql-caching.md  | 251 +++++-------
 .../0026-permission-aware-caching.md          | 365 +++++++-----------
 .../decisions/0027-client-side-caching.md     | 208 +++++-----
 4 files changed, 401 insertions(+), 569 deletions(-)

diff --git a/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md b/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
index df86a22f5..96f900178 100644
--- a/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
+++ b/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
@@ -32,6 +32,24 @@ DataLoader solves the N+1 query problem by batching and caching database request
 
 Without DataLoader, each relationship traversal triggers a separate database query. With 10 events each having a creator, you'd execute 1 query for events + 10 queries for creators = 11 total. DataLoader automatically batches those 10 creator queries into 1.
 
+**Query Batching Flow:**
+
+```mermaid
+sequenceDiagram
+    participant Resolver
+    participant DataLoader
+    participant Database
+    
+    Note over Resolver: Resolver requests user data for 10 events
+    Resolver->>DataLoader: load(userId1)
+    Resolver->>DataLoader: load(userId2)
+    Resolver->>DataLoader: load(userId3)
+    Note over DataLoader: Collects requests in current tick
+    DataLoader->>Database: SELECT * FROM users WHERE id IN (1,2,3)
+    Database-->>DataLoader: Return 3 users
+    DataLoader-->>Resolver: Distribute cached results to each caller
+```
+
 ## HTTP Batching - Network Request Consolidation
 
 HTTP Batching combines multiple GraphQL operations into a single HTTP request, reducing network overhead.
@@ -43,6 +61,25 @@ HTTP Batching combines multiple GraphQL operations into a single HTTP request, r
 
 When multiple React components independently fetch data, each triggers a separate HTTP request. HTTP Batching waits 20ms to collect operations and sends them together, eliminating redundant connection setup, headers, and SSL handshakes.
 
+**HTTP Batching Flow:**
+
+```mermaid
+sequenceDiagram
+    participant Component1
+    participant Component2
+    participant Apollo
+    participant Server
+    
+    Note over Component1,Component2: Multiple components render
+    Component1->>Apollo: query GetUser
+    Component2->>Apollo: query GetEvents
+    Note over Apollo: Wait 20ms to collect queries
+    Apollo->>Server: POST [GetUser, GetEvents]
+    Server-->>Apollo: [UserData, EventsData]
+    Apollo-->>Component1: UserData
+    Apollo-->>Component2: EventsData
+```
+
 ## useFragment + @nonreactive - Re-Render Optimization
 
 This pattern enables surgical cache updates and eliminates unnecessary re-renders, particularly valuable for list rendering.
@@ -60,6 +97,29 @@ This pattern enables surgical cache updates and eliminates unnecessary re-render
 
 This isn't a speed optimization - it's a re-render reduction pattern that prevents performance degradation at scale.
 
+**Re-Render Optimization Flow:**
+
+```mermaid
+graph TB
+    subgraph "Without useFragment"
+        Parent1[Parent Component]
+        Parent1 -->|passes full data objects| Child1A[Child 1]
+        Parent1 -->|passes full data objects| Child1B[Child 2]
+        Parent1 -->|passes full data objects| Child1C[Child 3]
+        Cache1[Apollo Cache] -.->|cache update| Parent1
+        Note1[Update Child 2 data<br/>Result: Parent + all 3 children re-render]
+    end
+    
+    subgraph "With useFragment + @nonreactive"
+        Parent2[Parent Component]
+        Parent2 -->|passes IDs only| Child2A[Child 1]
+        Parent2 -->|passes IDs only| Child2B[Child 2]
+        Parent2 -->|passes IDs only| Child2C[Child 3]
+        Cache2[Apollo Cache] -.->|direct subscription| Child2B
+        Note2[Update Child 2 data<br/>Result: Only Child 2 re-renders]
+    end
+
+
 ## Decision Drivers
 
 - **Performance**: Minimize network requests, database queries, and component re-renders
@@ -129,85 +189,25 @@ Chosen option: **Use all three patterns** - DataLoader, HTTP Batching, and useFr
 ### Implementation for ShareThrift
 
 **DataLoader (Server):**
-```typescript
-const loaders = {
-  userLoader: new DataLoader(batchLoadUsers),
-  eventLoader: new DataLoader(batchLoadEvents),
-  communityLoader: new DataLoader(batchLoadCommunities),
-};
-```
+- Configure loaders for User, Event, and Community entities
+- Initialize per-request to maintain security boundaries
+- Batch database queries within single operation execution
 
 **HTTP Batching (Client):**
-```typescript
-const batchLink = new BatchHttpLink({
-  uri: '/graphql',
-  batchMax: 10,
-  batchInterval: 20,
-});
-```
+- Configure BatchHttpLink with 20ms collection window
+- Set maximum batch size of 10 operations
+- Apply to authenticated GraphQL endpoint
 
 **Fragment Colocation (Client):**
-```typescript
-const USER_AVATAR_FRAGMENT = gql`
-  fragment UserAvatarData on User {
-    displayName
-    avatarUrl
-  }
-`;
-
-function UserAvatar({ user }) {
-  return <img src={user.avatarUrl} alt={user.displayName} />;
-}
-
-const GET_EVENT = gql`
-  query GetEvent {
-    event {
-      creator {
-        ...UserAvatarData
-      }
-    }
-  }
-  ${USER_AVATAR_FRAGMENT}
-`;
-```
+- Define fragments alongside components that use them
+- Compose fragments into parent queries
+- Enables component portability and self-documentation
 
 **useFragment + @nonreactive Pattern (Client):**
-```typescript
-// Parent query with @nonreactive
-const GET_EVENTS_QUERY = gql`
-  query GetEvents {
-    events {
-      id
-      ...EventCardData @nonreactive
-    }
-  }
-  ${EVENT_CARD_FRAGMENT}
-`;
-
-// Parent only re-renders when IDs change (events added/removed)
-function EventFeed() {
-  const { data } = useQuery(GET_EVENTS_QUERY);
-  const eventIds = data.events.map(event => event.id);
-  return eventIds.map(id => <EventCard key={id} eventId={id} />);
-}
-
-// Child reads from cache - only re-renders when THIS event changes
-function EventCard({ eventId }) {
-  const { data } = useFragment({
-    fragment: EVENT_CARD_FRAGMENT,
-    from: { __typename: 'Event', id: eventId },
-  });
-  
-  return (
-    <div>
-      <h3>{data.title}</h3>
-      <button onClick={() => toggleAttendance(eventId)}>
-        {data.isAttending ? 'Attending' : 'Join'}
-      </button>
-    </div>
-  );
-}
-```
+- Parent queries fetch IDs and mark fragments as @nonreactive
+- Parent re-renders only when list composition changes (items added/removed)
+- Child components use useFragment to read directly from cache
+- Cache updates trigger re-renders only in affected children
 
 ### Consequences
 
diff --git a/apps/docs/docs/decisions/0025-public-graphql-caching.md b/apps/docs/docs/decisions/0025-public-graphql-caching.md
index 708f6e198..7e6c3905c 100644
--- a/apps/docs/docs/decisions/0025-public-graphql-caching.md
+++ b/apps/docs/docs/decisions/0025-public-graphql-caching.md
@@ -63,134 +63,85 @@ Chosen option: **Separate endpoints** - `/graphql` for authenticated requests an
 
 ### Server Architecture
 
-```typescript
-// Single Apollo Server with dual endpoints
-
-const server = new ApolloServer({
-  typeDefs,
-  resolvers,
-  plugins: [
-    {
-      async requestDidStart() {
-        return {
-          async willSendResponse({ response, contextValue }) {
-            // Set cache headers based on endpoint
-            if (contextValue.isPublic) {
-              response.http.headers.set('Cache-Control', 'public, max-age=300, s-maxage=3600');
-            } else {
-              response.http.headers.set('Cache-Control', 'private, no-cache, no-store, must-revalidate');
-            }
-          },
-        };
-      },
-    },
-  ],
-  persistedQueries: { cache: undefined },
-  csrfPrevention: false, // Allow GET requests, requires further security safeguards, headers, rate limiting, etc.
-});
-
-// Authenticated endpoint
-app.use('/graphql', expressMiddleware(server, {
-  context: async () => ({
-    loaders: createDataLoaders(collections),
-    collections,
-    isPublic: false,
-  }),
-}));
-
-// Public endpoint with GET request transformation
-app.use('/graphql-public',
-  (req, _res, next) => {
-    // Transform GET query params to req.body for Apollo Server
-    if (req.method === 'GET' && req.query) {
-      req.body = {
-        operationName: req.query.operationName,
-        variables: req.query.variables ? JSON.parse(req.query.variables) : undefined,
-        extensions: req.query.extensions ? JSON.parse(req.query.extensions) : undefined,
-        query: req.query.query,
-      };
-    }
-    next();
-  },
-  expressMiddleware(server, {
-    context: async () => ({
-      loaders: createDataLoaders(collections),
-      collections,
-      isPublic: true,
-    }),
-  })
-);
+**Dual Endpoint Configuration:**
+- Single Apollo Server instance serves both endpoints
+- `/graphql` - Authenticated endpoint with POST requests and private cache headers
+- `/graphql-public` - Public endpoint with GET requests and CDN-friendly cache headers
+
+**Cache Control Strategy:**
+- Public endpoint: `Cache-Control: public, max-age=300, s-maxage=3600` (5min browser, 1hr CDN)
+- Authenticated endpoint: `Cache-Control: private, no-cache, no-store, must-revalidate`
+
+**Security Considerations:**
+- Public endpoint disables CSRF prevention to allow GET requests
+- Must implement additional safeguards: rate limiting, request validation, header checks
+- GET request query parameters transformed to request body for Apollo Server compatibility
+
+**Request Flow:**
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant CDN
+    participant Server
+    
+    Note over Client,Server: Public Endpoint (/graphql-public)
+    Client->>CDN: GET /graphql-public?extensions={hash}
+    alt Cache Hit
+        CDN-->>Client: Return cached response (< 5ms)
+    else Cache Miss
+        CDN->>Server: Forward GET request
+        Server-->>CDN: Response + Cache-Control: public
+        CDN-->>Client: Response (cached for future)
+    end
+    
+    Note over Client,Server: Authenticated Endpoint (/graphql)
+    Client->>Server: POST /graphql + Authorization header
+    Server-->>Client: Response + Cache-Control: private
+    Note over CDN: Not cached by CDN
 ```
 
 ### Client Configuration
 
-```typescript
-// Authenticated Apollo Client
-export const authenticatedClient = new ApolloClient({
-  uri: 'http://localhost:4000/graphql',
-  cache: new InMemoryCache(),
-  link: from([
-    setContext((_, { headers }) => {
-      const token = localStorage.getItem('auth_token');
-      return {
-        headers: {
-          ...headers,
-          authorization: token ? `Bearer ${token}` : '',
-        },
-      };
-    }),
-    createHttpLink({ uri: 'http://localhost:4000/graphql' }),
-  ]),
-});
-
-// Public Apollo Client with APQ and GET requests
-export const publicClient = new ApolloClient({
-  uri: 'http://localhost:4000/graphql-public',
-  cache: new InMemoryCache(),
-  link: createPersistedQueryLink({
-    sha256: async (query) => {
-      const { createHash } = await import('crypto-hash');
-      return createHash('sha256').update(query).digest('hex');
-    },
-    useGETForHashedQueries: true,
-  }).concat(
-    createHttpLink({
-      uri: 'http://localhost:4000/graphql-public',
-    })
-  ),
-});
-```
+**Authenticated Client:**
+- Targets `/graphql` endpoint
+- Adds JWT token from localStorage to Authorization header
+- Uses POST requests for all operations
+- Compatible with HTTP batching
+
+**Public Client:**
+- Targets `/graphql-public` endpoint
+- Configures Automatic Persisted Queries (APQ) with SHA-256 hashing
+- Enables GET requests for hashed queries via `useGETForHashedQueries`
+- No authorization headers sent
+- Leverages CDN and network provider caching
 
 ### Schema Design
 
-Define public queries explicitly:
+**Public Schema Subset:**
+- Explicitly defined queries for unauthenticated access
+- Examples: `publicFeed`, `publicPost`, `publicUser`
+- Returns sanitized types without sensitive fields
+- Clearly prefixed with `public` for auditing
 
-```graphql
-# Public schema subset
-type Query {
-  publicFeed(first: Int, after: String): PostConnection!
-  publicPost(id: ID!): Post
-  publicUser(username: String!): PublicUserProfile
-}
-
-# Authenticated schema (full access)
-type Query {
-  feed(first: Int, after: String): PostConnection!
-  myFeed: PostConnection!
-  myProfile: UserProfile!
-  # ... all other queries
-}
-```
+**Authenticated Schema:**
+- Full query set including user-specific operations
+- Includes personalized queries: `myFeed`, `myProfile`
+- Returns complete types with all fields
+- Requires valid JWT token
 
 ### Cache-Control Headers
 
-```typescript
-// Public endpoint - 5 min browser cache, 1 hour CDN cache
-response.http.headers.set('Cache-Control', 'public, max-age=300, s-maxage=3600');
+**Public Endpoint Strategy:**
+- `max-age=300`: Browser caches for 5 minutes
+- `s-maxage=3600`: CDN/shared caches for 1 hour
+- `public`: Explicitly allows intermediate caching
 
-// Authenticated endpoint - no caching
-response.http.headers.set('Cache-Control', 'private, no-cache, no-store, must-revalidate');
-```
+**Authenticated Endpoint Strategy:**
+- `private`: Only browser may cache (not CDN)
+- `no-cache`: Must revalidate before using cached copy
+- `no-store`: Prevent any caching mechanism from storing data
+- `must-revalidate`: Strict cache validation required
 
 ## Automatic Persisted Queries (APQ)
 
@@ -217,19 +168,15 @@ GET /graphql-public?extensions={"persistedQuery":{"version":1,"sha256Hash":"abc1
 
 ### Implementation
 
-```typescript
-import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
-import { sha256 } from 'crypto-hash';
+**Client-Side:**
+- Import persisted query link from Apollo Client
+- Configure SHA-256 hashing function
+- Enable GET requests for hashed queries
+- Chain with HTTP link
 
-const link = createPersistedQueryLink({ 
-  sha256,
-  useGETForHashedQueries: true,
-}).concat(httpLink);
-```
-
-### Server Support
-
-Apollo Server supports APQ out-of-the-box (enabled by default).
+**Server-Side:**
+- Apollo Server supports APQ out-of-the-box (enabled by default)
+- No additional configuration required
 
 ## Consequences
 
@@ -292,44 +239,20 @@ Apollo Server supports APQ out-of-the-box (enabled by default).
 
 This approach uses a single `/graphql` endpoint for both authenticated and public queries, with conditional logic to determine when to include authentication headers.
 
-**Implementation Pattern:**
-```typescript
-// Client conditionally adds auth based on operation name
-const conditionalAuthLink = setContext((operation, { headers }) => {
-  const authenticatedOperations = ['GetFeed', 'GetPost', 'MyProfile'];
-  const shouldAuthenticate = authenticatedOperations.includes(operation.operationName || '');
-  
-  if (shouldAuthenticate) {
-    return { headers: { ...headers, authorization: `Bearer ${token}` } };
-  }
-  
-  // For public queries, remove auth and signal the server
-  return { 
-    headers: { 
-      ...headers, 
-      authorization: undefined,
-      'X-Public-Query': 'true' // Custom header to trigger cache headers
-    } 
-  };
-});
-
-// Server checks custom header to determine cache policy
-app.use('/graphql', expressMiddleware(server, {
-  context: async ({ req }) => ({
-    isPublic: req.headers['x-public-query'] === 'true',
-    // ... other context
-  })
-}));
-```
-
 **How It Works:**
 1. Client maintains whitelist of operations requiring authentication
-2. `setContext` checks operation name before adding auth header
-3. Public queries send custom `X-Public-Query` header instead
-4. Server reads header and sets cache policy accordingly
-5. Apollo Server plugin applies correct `Cache-Control` headers
-
-**Note:** This approach is not recommended due to security risks of misconfigured queries exposing tokens to CDN and the maintenance burden of maintaining operation whitelists.
+2. Context link checks operation name before adding auth header
+3. Public queries send custom header to signal caching eligibility
+4. Server reads header and sets cache policy dynamically
+5. Single Apollo Server instance handles both request types
+
+**Drawbacks:**
+- Security risk: Misconfigured whitelist could expose tokens to CDN
+- Maintenance burden: Must keep operation whitelist synchronized
+- Audit complexity: Harder to track which queries are public
+- Testing overhead: More edge cases to validate
+
+**Not Recommended** - Separate endpoints provide clearer security boundaries
 
 
 ## More Information
diff --git a/apps/docs/docs/decisions/0026-permission-aware-caching.md b/apps/docs/docs/decisions/0026-permission-aware-caching.md
index ddc4699d9..140585ce7 100644
--- a/apps/docs/docs/decisions/0026-permission-aware-caching.md
+++ b/apps/docs/docs/decisions/0026-permission-aware-caching.md
@@ -60,110 +60,105 @@ Chosen option: **Permission-aware cache keys** - Include user permissions in cac
 
 ### Cache Key Structure
 
-```typescript
-interface CacheKey {
-  query: string;              // Operation name: "GetFeedWithAnalytics"
-  variables?: Record<string, any>;  // Query variables: { first: 5 }
-  userId?: string;            // User ID: "507f1f77bcf86cd799439011"
-  role?: string;              // User role: "admin" | "user"
-  permissions?: string[];     // Additional permissions: ["read:analytics"]
-}
+**Components:**
+- **Query**: Operation name (e.g., "GetFeedWithAnalytics")
+- **Variables**: Query parameters (e.g., `{ first: 5 }`)
+- **User ID**: Unique user identifier (e.g., "507f1f77bcf86cd799439011")
+- **Role**: User role (e.g., "admin", "user")
+- **Permissions**: Additional permission flags (e.g., ["read:analytics"])
+
+**Generated Key Example:**
+```
+GetFeedWithAnalytics::{"first":5}::alice::admin::[]
+```
+
+**Cache Isolation:**
 
-// Generated key (stringified):
-// "GetFeedWithAnalytics::{"first":5}::alice::admin::[]"
+```mermaid
+graph LR
+    subgraph "Admin Cache Entry"
+        A[GetEvents::alice::admin]
+    end
+    
+    subgraph "User Cache Entry"
+        B[GetEvents::bob::user]
+    end
+    
+    subgraph "Shared User Cache"
+        C[GetEvents::charlie::user]
+        D[GetEvents::diane::user]
+    end
+    
+    C -.shares.-> D
+    
+    A -.isolated from.-> B
+    B -.isolated from.-> A
 ```
 
 ### Permission-Aware Resolver
 
-```typescript
-Post: {
-  analytics: async (parent, _, { user, cache }) => {
-    // Permission check
-    if (user?.role !== 'admin') {
-      return null;  // Don't reveal analytics to non-admins
-    }
-
-    // Cache key includes user role
-    const cacheKey = {
-      query: 'PostAnalytics',
-      variables: { postId: parent.id },
-      userId: user.id,
-      role: user.role,
-    };
-
-    // Check cache first
-    const cached = cache.get(cacheKey);
-    if (cached) return cached;
-
-    // Fetch from database
-    const analytics = await fetchAnalytics(parent.id);
-
-    // Store in cache with 30s TTL
-    cache.set(cacheKey, analytics, 30000);
-
-    return analytics;
-  }
-}
+**Resolution Flow:**
+1. **Permission Check**: Validate user has required role/permissions
+2. **Early Return**: Return null for unauthorized requests (don't cache)
+3. **Cache Key Generation**: Include query, variables, userId, and role
+4. **Cache Lookup**: Check if entry exists for this permission context
+5. **Database Fetch**: On cache miss, fetch from database
+6. **Cache Storage**: Store with TTL (typically 30-60 seconds)
+7. **Return Data**: Provide cached or fresh data to client
+
+**Resolver Flow:**
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Resolver
+    participant Cache
+    participant Database
+    
+    Client->>Resolver: Query PostAnalytics
+    Resolver->>Resolver: Check user.role == 'admin'
+    alt Not Admin
+        Resolver-->>Client: null (unauthorized)
+    else Is Admin
+        Resolver->>Cache: get(PostAnalytics::alice::admin)
+        alt Cache Hit
+            Cache-->>Resolver: Return cached data
+            Resolver-->>Client: Cached analytics
+        else Cache Miss
+            Resolver->>Database: fetchAnalytics(postId)
+            Database-->>Resolver: Fresh data
+            Resolver->>Cache: set(key, data, 30s TTL)
+            Resolver-->>Client: Fresh analytics
+        end
+    end
 ```
 
 ### Cache Implementation
 
-```typescript
-class PermissionAwareCache {
-  private cache: Map<string, CacheEntry<any>>;
-  private maxSize: number = 1000;
-  private defaultTTL: number = 60000; // 1 minute
-
-  private generateKey(cacheKey: CacheKey): string {
-    return [
-      cacheKey.query,
-      JSON.stringify(cacheKey.variables || {}),
-      cacheKey.userId || 'anonymous',
-      cacheKey.role || 'none',
-      JSON.stringify(cacheKey.permissions?.sort() || []),
-    ].join('::');
-  }
+**Core Features:**
+- In-memory Map-based storage for fast lookups (< 1ms)
+- Configurable max size (default: 1000 entries)
+- Configurable default TTL (default: 60 seconds)
+- LRU (Least Recently Used) eviction when max size reached
 
-  get<T>(cacheKey: CacheKey): T | null {
-    const key = this.generateKey(cacheKey);
-    const entry = this.cache.get(key);
+**Key Methods:**
 
-    if (!entry || Date.now() - entry.timestamp > entry.ttl) {
-      this.cache.delete(key);
-      return null;
-    }
+**generateKey**: Concatenates query, variables, userId, role, and permissions into unique string
 
-    return entry.data;
-  }
+**get**: 
+- Generates cache key from components
+- Checks if entry exists and is not expired
+- Returns data or null (with automatic cleanup of expired entries)
 
-  set<T>(cacheKey: CacheKey, data: T, ttl?: number): void {
-    if (this.cache.size >= this.maxSize) {
-      // Simple LRU: delete oldest entry
-      const firstKey = this.cache.keys().next().value;
-      this.cache.delete(firstKey);
-    }
-
-    const key = this.generateKey(cacheKey);
-    this.cache.set(key, {
-      data,
-      timestamp: Date.now(),
-      ttl: ttl || this.defaultTTL,
-    });
-  }
+**set**:
+- Enforces max size limit with LRU eviction
+- Stores data with timestamp and TTL
+- Allows per-entry TTL override
 
-  // Invalidate entries matching pattern
-  invalidate(pattern: { query?: string; userId?: string; role?: string }): number {
-    let deletedCount = 0;
-    for (const [key] of this.cache.entries()) {
-      if (this.matchesPattern(key, pattern)) {
-        this.cache.delete(key);
-        deletedCount++;
-      }
-    }
-    return deletedCount;
-  }
-}
-```
+**invalidate**:
+- Pattern-based cache clearing
+- Supports wildcard matching on query, userId, or role
+- Returns count of deleted entries for monitoring
 
 
 ## Consequences
@@ -198,16 +193,16 @@ class PermissionAwareCache {
 ### Granularity
 
 **Coarse (role-level):**
-```typescript
-cacheKey = { query, variables, role }
-// All admins share cache
-```
+- Cache key includes query, variables, and role only
+- All users with same role share cache entry
+- Best for non-personalized data
+- Example: All admins see same analytics dashboard
 
 **Fine (user-level):**
-```typescript
-cacheKey = { query, variables, userId, role }
-// Each user has own cache
-```
+- Cache key includes query, variables, userId, and role
+- Each user has isolated cache entry
+- Required for personalized data
+- Example: Each user's personal feed
 
 **Recommendation**: 
 - Use role-level for data that doesn't vary per user
@@ -218,38 +213,29 @@ cacheKey = { query, variables, userId, role }
 
 ### Time-Based (TTL)
 
-```typescript
-cache.set(key, data, 60000); // Expires after 60s
-```
+Entries automatically expire after configured duration (e.g., 60 seconds).
 
 **Pros:** Simple, predictable
 **Cons:** May serve stale data for TTL duration
 
 ### Event-Based
 
-```typescript
-// When post is updated
-Mutation: {
-  updatePost: async (_, { id, content }) => {
-    await db.posts.update(id, content);
-    cache.invalidate({ query: 'GetFeed' }); // Clear all feed caches
-    cache.invalidate({ query: 'GetPost', variables: { id } });
-  }
-}
-```
+Manually invalidate cache entries when underlying data changes (e.g., on mutations).
+
+**Process:**
+1. Update data in database
+2. Invalidate affected cache queries
+3. Next request fetches fresh data
 
 **Pros:** Always fresh data
 **Cons:** More complex, can invalidate too aggressively
 
 ### Hybrid (Recommended)
 
-```typescript
-// 30s TTL + invalidation on mutations
-cache.set(key, data, 30000);
-
-// On mutation
-cache.invalidate({ query: 'GetFeed' });
-```
+Combine TTL expiration with event-based invalidation:
+- Set reasonable TTL (30-60 seconds)
+- Invalidate on mutations for immediate freshness
+- TTL serves as safety net for missed invalidations
 
 **Balance:** Fresh data for mutations, caching for reads
 
@@ -260,148 +246,65 @@ cache.invalidate({ query: 'GetFeed' });
 **Problem:** Alice is promoted from `user` to `admin`
 
 **Solution:**
-```typescript
-async function updateUserRole(userId: string, newRole: string) {
-  await db.users.update(userId, { role: newRole });
-  
-  // Invalidate all cache entries for this user
-  cache.invalidate({ userId });
-  
-  // User's next request will generate fresh cache with new permissions
-}
-```
+1. Update user role in database
+2. Invalidate all cache entries matching userId
+3. Next request generates fresh cache with new role
+4. User immediately sees admin-only data
 
 ### Scenario 2: Data Update
 
 **Problem:** Admin updates a post, all users should see new content
 
 **Solution:**
-```typescript
-Mutation: {
-  updatePost: async (_, { id, content }) => {
-    await db.posts.update(id, content);
-    
-    // Invalidate feed for ALL roles
-    cache.invalidate({ query: 'GetFeed' });
-    cache.invalidate({ query: 'GetPost' });
-    
-    // Next request for any user will fetch fresh data
-  }
-}
-```
+1. Update post in database
+2. Invalidate all cache entries for affected queries (GetFeed, GetPost)
+3. Clear cache across all user roles
+4. Next request for any user fetches fresh data
 
 ### Scenario 3: Permission Check Change
 
 **Problem:** Analytics permission logic changes (now requires `premium` flag)
 
 **Solution:**
-```typescript
-// Old resolver
-Post: {
-  analytics: async (parent, _, { user }) => {
-    if (user?.role !== 'admin') return null;
-    // ...
-  }
-}
-
-// New resolver
-Post: {
-  analytics: async (parent, _, { user }) => {
-    if (user?.role !== 'admin' && !user?.premium) return null;
-    // Cache key now includes premium flag
-    const cacheKey = {
-      query: 'PostAnalytics',
-      variables: { postId: parent.id },
-      userId: user.id,
-      role: user.role,
-      permissions: user.premium ? ['premium'] : [],
-    };
-    // ...
-  }
-}
-
-// Clear all analytics caches during deployment
-cache.invalidate({ query: 'PostAnalytics' });
-```
+1. Update resolver permission check to require admin OR premium
+2. Modify cache key generation to include premium flag in permissions array
+3. During deployment, invalidate all PostAnalytics cache entries
+4. New cache entries generated with updated permission model
+5. Admin and premium users both see analytics (in separate cache entries)
 
 ## Edge Cases & Mitigations
 
 ### Edge Case: Permission Check in Middle of Resolver Chain
 
 **Problem:**
-```typescript
-Query: {
-  posts: async () => {
-    return await db.posts.find(); // Fetches all posts
-  }
-}
-
-Post: {
-  analytics: async (parent, _, { user }) => {
-    if (user?.role !== 'admin') return null; // Permission check HERE
-    return fetchAnalytics(parent.id);
-  }
-}
-```
-
-If we cache at `Query.posts`, admin and user caches would be identical!
+Root query fetches all posts without permission check, but nested field `analytics` requires admin role. If we cache at root query level, admin and user caches would be identical.
 
-**Solution:** Cache at the field level where permission check occurs:
-```typescript
-Post: {
-  analytics: async (parent, _, { user, cache }) => {
-    if (user?.role !== 'admin') return null;
-    
-    const cacheKey = {
-      query: 'PostAnalytics',
-      variables: { postId: parent.id },
-      role: user.role,
-    };
-    
-    const cached = cache.get(cacheKey);
-    if (cached) return cached;
-    
-    const analytics = await fetchAnalytics(parent.id);
-    cache.set(cacheKey, analytics);
-    return analytics;
-  }
-}
-```
+**Solution:**
+Cache at the field level where permission check occurs:
+1. Root query (posts) caches without permission context
+2. Nested field (analytics) caches with role in key
+3. Admin gets cached analytics, user gets null
+4. Two separate cache entries maintain security boundary
 
 ### Edge Case: Dynamic Permissions
 
 **Problem:** User has permission `["posts:read:own"]` - can only read their own posts
 
-**Solution:** Include ownership in cache key:
-```typescript
-const cacheKey = {
-  query: 'GetPosts',
-  variables,
-  userId: user.id, // Include user ID
-  permissions: user.permissions,
-};
-```
-
-Result: Each user gets own cache entry, no data leakage
+**Solution:**
+1. Include userId in cache key (not just role)
+2. Include full permissions array in cache key
+3. Each user gets isolated cache entry
+4. No risk of cross-user data leakage
 
 ### Edge Case: Memory Leak from User Churn
 
 **Problem:** 10,000 users log in once, cache grows unbounded
 
-**Solution:** Enforce `maxSize` with LRU eviction:
-```typescript
-class PermissionAwareCache {
-  private maxSize = 1000;
-
-  set(key, data) {
-    if (this.cache.size >= this.maxSize) {
-      const oldestKey = this.cache.keys().next().value;
-      this.cache.delete(oldestKey); // Evict oldest
-    }
-    this.cache.set(key, data);
-  }
-}
-```
+**Solution:**
+1. Enforce maximum cache size limit (e.g., 1000 entries)
+2. Implement LRU (Least Recently Used) eviction strategy
+3. When max size reached, remove oldest entry before adding new one
+4. Protects against memory exhaustion from one-time users
 
 ## Monitoring & Observability
 
diff --git a/apps/docs/docs/decisions/0027-client-side-caching.md b/apps/docs/docs/decisions/0027-client-side-caching.md
index 6274734c8..9a2cf5a45 100644
--- a/apps/docs/docs/decisions/0027-client-side-caching.md
+++ b/apps/docs/docs/decisions/0027-client-side-caching.md
@@ -57,60 +57,42 @@ Apollo Client offers multiple fetch policies:
 #### cache-first (Default)
 Read from cache, fetch on cache miss. Best for static/public data.
 
-```typescript
-useQuery(GET_PRODUCT_CATALOG, { fetchPolicy: 'cache-first' });
-```
+**Behavior**: Check cache first, only fetch if data not found
 
-Use cases: Product catalogs, blog posts, reference data
+**Use cases**: Product catalogs, blog posts, reference data
 
 #### network-only
 Always fetch fresh, appropriate for sensitive data.
 
-```typescript
-useQuery(GET_BANK_BALANCE, { fetchPolicy: 'network-only' });
-```
+**Behavior**: Always fetch from network, update cache but never read from it
 
-Use cases: Bank balances, private messages, real-time data
+**Use cases**: Bank balances, private messages, real-time data
 
 #### cache-and-network
 Show cached instantly, refresh in background.
 
-```typescript
-useQuery(GET_USER_FEED, { fetchPolicy: 'cache-and-network' });
-```
+**Behavior**: Return cached data immediately, then fetch fresh and update
 
-Use cases: Social feeds, dashboards
+**Use cases**: Social feeds, dashboards
 
 #### no-cache
 Bypasses cache entirely for single-use data.
 
-```typescript
-useQuery(GET_OTP, { fetchPolicy: 'no-cache' });
-```
+**Behavior**: Fetch from network, don't read or write to cache
 
-Use cases: OTP codes, reset tokens
+**Use cases**: OTP codes, reset tokens
 
 ### Field-Level Security
 
-Use field policies to mask sensitive data:
-
-```typescript
-const cache = new InMemoryCache({
-  typePolicies: {
-    User: {
-      fields: {
-        ssn: {
-          read() {
-            return '***-**-****'; // Always masked
-          },
-        },
-      },
-    },
-  },
-});
-```
+Use field policies to mask sensitive data even if server returns real values.
+
+**Implementation:**
+- Configure type policies in InMemoryCache
+- Define custom read functions for sensitive fields
+- Read function returns masked value (e.g., '***-**-****')
+- Original server data never exposed in cache
 
-Benefits: Defense-in-depth, cache inspector safety, redacted logs
+**Benefits**: Defense-in-depth, cache inspector safety, redacted logs
 
 ### Varying Field Selections
 
@@ -125,40 +107,57 @@ Key insight: Query broader fields first, narrower queries benefit from cache.
 
 ### useFragment for Cache Reads
 
-Read cached data without network request:
+Read cached data without network request.
 
-```typescript
-function PostCard({ id }: { id: string }) {
-  const { complete, data } = useFragment({
-    fragment: POST_CARD_FRAGMENT,
-    from: { __typename: 'Post', id },
-  });
+**Process:**
+- Component receives entity ID as prop
+- useFragment reads directly from cache using fragment definition
+- Returns complete flag (true if all fields available) and data
+- Component subscribes to cache updates for that entity
 
-  if (!complete) return null;
-  return <div>{data.content}</div>;
-}
-```
+**Benefits**: Zero network overhead, live updates, avoids prop drilling
 
-Benefits: Zero network overhead, live updates, avoids prop drilling
-
-See ADR 0024 for re-render optimization details.
+See [ADR 0024](./0024-usefragment-vs-httpbatch-dataloader.md) for re-render optimization details.
 
 ### Optimistic Updates
 
-Update UI instantly before server confirms:
-
-```typescript
-const [likePost] = useMutation(LIKE_POST, {
-  optimisticResponse: {
-    likePost: { __typename: 'Post', id: postId, likeCount: currentLikeCount + 1 },
-  },
-});
+Update UI instantly before server confirms mutation success.
+
+**Process:**
+1. User triggers mutation (e.g., like post)
+2. Client immediately updates cache with predicted response
+3. UI reflects change instantly
+4. Mutation sent to server
+5. On success: cache already correct
+6. On failure: Apollo automatically rolls back optimistic update
+
+**Use cases**: Likes, favorites, toggles
+
+**Optimistic Update Flow:**
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Cache
+    participant Server
+    
+    User->>UI: Click "Like"
+    UI->>Cache: Optimistic update (likeCount + 1)
+    Cache-->>UI: Updated data
+    UI-->>User: Show liked state instantly
+    UI->>Server: Send LIKE_POST mutation
+    alt Success
+        Server-->>UI: Confirm success
+        Note over Cache: Already correct
+    else Failure
+        Server-->>UI: Return error
+        UI->>Cache: Rollback optimistic update
+        Cache-->>UI: Original data
+        UI-->>User: Show error, revert to unliked
+    end
 ```
 
-Flow: UI updates instantly, mutation sent to server, Apollo auto-rolls back on failure.
-
-Use cases: Likes, favorites, toggles
-
 ## Decision Outcome
 
 Chosen option: **Tiered caching strategy** based on data sensitivity and freshness requirements.
@@ -175,57 +174,62 @@ Chosen option: **Tiered caching strategy** based on data sensitivity and freshne
 
 **Optimistic Updates**: Use for likes, follows, attendance toggles. Avoid for complex validations and transactions.
 
+**Cache Policy Decision Flow:**
+
+```mermaid
+graph TD
+    A[Query Execution] --> B{Data Sensitivity}
+    B -->|Highly Sensitive| C[no-cache]
+    B -->|Sensitive| D[network-only]
+    B -->|User-Specific| E[cache-and-network]
+    B -->|Public/Static| F[cache-first]
+    
+    C --> G[Bypass cache entirely]
+    D --> H[Always fetch, don't cache]
+    E --> I[Return cached, fetch fresh in background]
+    F --> J[Return cached, fetch only on miss]
+    
+    style C fill:#f44
+    style D fill:#fa4
+    style E fill:#4af
+    style F fill:#4f4
+```
+
 ### Implementation for ShareThrift
 
 **Configure Cache:**
-```typescript
-const cache = new InMemoryCache({
-  typePolicies: {
-    User: {
-      keyFields: ['id'],
-      fields: {
-        email: { read() { return '***@***.com'; } },
-      },
-    },
-  },
-});
-```
+- Initialize InMemoryCache with type policies
+- Define key fields for entity identification (typically 'id')
+- Configure field policies for sensitive data masking
+- Example: Mask email field to always return redacted value
 
 **Apply Policies:**
-```typescript
-// Public event listings
-useQuery(GET_PUBLIC_EVENTS, { fetchPolicy: 'cache-first' });
-
-// User-specific feed
-useQuery(GET_MY_FEED, { fetchPolicy: 'cache-and-network' });
-
-// Payment information
-useQuery(GET_PAYMENT_METHODS, { fetchPolicy: 'network-only' });
-```
+- **Public event listings**: `cache-first` for maximum caching
+- **User-specific feed**: `cache-and-network` for instant display with background refresh
+- **Payment information**: `network-only` to always fetch fresh, never cache
 
 ## Cache Invalidation
 
 ### Refetch Queries
-```typescript
-useMutation(UPDATE_POST, {
-  refetchQueries: ['GetFeed'],
-});
-```
+
+Specify queries to automatically refetch after mutation completes.
+- Provide array of query names
+- Apollo automatically re-executes those queries
+- Simple but can cause unnecessary network requests
 
 ### Cache Eviction
-```typescript
-useMutation(DELETE_POST, {
-  update(cache) {
-    cache.evict({ id: cache.identify({ __typename: 'Post', id: postId }) });
-    cache.gc();
-  },
-});
-```
+
+Manually remove entries from cache after mutation.
+- Use `cache.evict()` to remove specific entity by ID
+- Use `cache.gc()` to garbage collect orphaned references
+- More precise than refetchQueries, avoids network requests
 
 ### Polling (use sparingly)
-```typescript
-useQuery(GET_NOTIFICATIONS, { pollInterval: 5000 });
-```
+
+Periodically refetch query at fixed interval (e.g., every 5 seconds).
+- Simple real-time updates for non-critical data
+- Inefficient compared to subscriptions
+- Use only when subscriptions not feasible
 
 ## Tooling and Debugging
 
@@ -238,9 +242,11 @@ Filter by `graphql` to verify cache behavior:
 - network-only: always hits network
 
 ### Cache Debugging
-```typescript
-console.log(client.cache.extract()); // View entire cache
-```
+
+Extract entire cache contents for inspection.
+- Use `client.cache.extract()` to view all cached entities
+- Helpful for debugging unexpected cache behavior
+- Can log to console or use Apollo DevTools for visual inspection
 
 ## Consequences
 

From ef604365c8e7185ea525844f5fc74834b70fb30b Mon Sep 17 00:00:00 2001
From: Jason Hankins <jason.hankins27@gmail.com>
Date: Wed, 17 Dec 2025 11:18:43 -0500
Subject: [PATCH 05/10] add mermain renders to docusaurus

---
 apps/docs/docusaurus.config.ts |   5 +
 apps/docs/package.json         |   1 +
 pnpm-lock.yaml                 | 930 +++++++++++++++++++++++++++++++++
 3 files changed, 936 insertions(+)

diff --git a/apps/docs/docusaurus.config.ts b/apps/docs/docusaurus.config.ts
index 39fd33921..96733766a 100644
--- a/apps/docs/docusaurus.config.ts
+++ b/apps/docs/docusaurus.config.ts
@@ -36,6 +36,11 @@ const config: Config = {
 		locales: ['en'],
 	},
 
+	markdown: {
+		mermaid: true,
+	},
+	themes: ['@docusaurus/theme-mermaid'],
+
 	presets: [
 		[
 			'classic',
diff --git a/apps/docs/package.json b/apps/docs/package.json
index c7a5705c1..5633f21a9 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -20,6 +20,7 @@
 	"dependencies": {
 		"@docusaurus/core": "3.9.2",
 		"@docusaurus/preset-classic": "3.9.2",
+		"@docusaurus/theme-mermaid": "^3.9.2",
 		"@mdx-js/react": "^3.0.0",
 		"clsx": "^2.0.0",
 		"prism-react-renderer": "^2.3.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7f2312a78..5c3fc5f24 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -180,6 +180,9 @@ importers:
       '@docusaurus/preset-classic':
         specifier: 3.9.2
         version: 3.9.2(@algolia/client-search@5.41.0)(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(@types/react@19.2.2)(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(search-insights@2.17.3)(typescript@5.6.3)
+      '@docusaurus/theme-mermaid':
+        specifier: ^3.9.2
+        version: 3.9.2(@docusaurus/plugin-content-docs@3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3))(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3)
       '@mdx-js/react':
         specifier: ^3.0.0
         version: 3.1.1(@types/react@19.2.2)(react@19.2.0)
@@ -1485,6 +1488,9 @@ packages:
       react: '>=19.0.0'
       react-dom: '>=19.0.0'
 
+  '@antfu/install-pkg@1.1.0':
+    resolution: {integrity: sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==}
+
   '@apollo/cache-control-types@1.0.3':
     resolution: {integrity: sha512-F17/vCp7QVwom9eG7ToauIKdAxpSoadsJnqIfyryLFSkLSOEqu+eC5Z3N8OXcUVStuOMcNHlyraRsA6rRICu4g==}
     peerDependencies:
@@ -2345,6 +2351,24 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@braintree/sanitize-url@7.1.1':
+    resolution: {integrity: sha512-i1L7noDNxtFyL5DmZafWy1wRVhGehQmzZaz1HiN5e7iylJMSZR7ekOV7NsIqa5qBldlLrsKv4HbgFUVlQrz8Mw==}
+
+  '@chevrotain/cst-dts-gen@11.0.3':
+    resolution: {integrity: sha512-BvIKpRLeS/8UbfxXxgC33xOumsacaeCKAjAeLyOn7Pcp95HiRbrpl14S+9vaZLolnbssPIUuiUd8IvgkRyt6NQ==}
+
+  '@chevrotain/gast@11.0.3':
+    resolution: {integrity: sha512-+qNfcoNk70PyS/uxmj3li5NiECO+2YKZZQMbmjTqRI3Qchu8Hig/Q9vgkHpI3alNjr7M+a2St5pw5w5F6NL5/Q==}
+
+  '@chevrotain/regexp-to-ast@11.0.3':
+    resolution: {integrity: sha512-1fMHaBZxLFvWI067AVbGJav1eRY7N8DDvYCTwGBiE/ytKBgP8azTdgyrKyWZ9Mfh09eHWb5PgTSO8wi7U824RA==}
+
+  '@chevrotain/types@11.0.3':
+    resolution: {integrity: sha512-gsiM3G8b58kZC2HaWR50gu6Y1440cHiJ+i3JUvcp/35JchYejb2+5MVeJK0iKThYpAa/P2PYFV4hoi44HD+aHQ==}
+
+  '@chevrotain/utils@11.0.3':
+    resolution: {integrity: sha512-YslZMgtJUyuMbZ+aKvfF3x1f5liK4mWNxghFRv7jqRR9C3R3fAOGTTKvxXDa2Y1s9zSbcpuO0cAxDYsc9SrXoQ==}
+
   '@chromatic-com/storybook@4.1.2':
     resolution: {integrity: sha512-QAWGtHwib0qsP5CcO64aJCF75zpFgpKK3jNpxILzQiPK3sVo4EmnVGJVdwcZWpWrGdH8E4YkncGoitw4EXzKMg==}
     engines: {node: '>=20.0.0', yarn: '>=1.22.18'}
@@ -2876,6 +2900,17 @@ packages:
       react: ^18.0.0 || ^19.0.0
       react-dom: ^18.0.0 || ^19.0.0
 
+  '@docusaurus/theme-mermaid@3.9.2':
+    resolution: {integrity: sha512-5vhShRDq/ntLzdInsQkTdoKWSzw8d1jB17sNPYhA/KvYYFXfuVEGHLM6nrf8MFbV8TruAHDG21Fn3W4lO8GaDw==}
+    engines: {node: '>=20.0'}
+    peerDependencies:
+      '@mermaid-js/layout-elk': ^0.1.9
+      react: ^18.0.0 || ^19.0.0
+      react-dom: ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@mermaid-js/layout-elk':
+        optional: true
+
   '@docusaurus/theme-search-algolia@3.9.2':
     resolution: {integrity: sha512-GBDSFNwjnh5/LdkxCKQHkgO2pIMX1447BxYUBG2wBiajS21uj64a+gH/qlbQjDLxmGrbrllBrtJkUHxIsiwRnw==}
     engines: {node: '>=20.0'}
@@ -3456,6 +3491,12 @@ packages:
     resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==}
     engines: {node: '>=18.18'}
 
+  '@iconify/types@2.0.0':
+    resolution: {integrity: sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==}
+
+  '@iconify/utils@3.1.0':
+    resolution: {integrity: sha512-Zlzem1ZXhI1iHeeERabLNzBHdOa4VhQbqAcOQaMKuTuyZCpwKbC2R4Dd0Zo3g9EAc+Y4fiarO8HIHRAth7+skw==}
+
   '@inquirer/external-editor@1.0.2':
     resolution: {integrity: sha512-yy9cOoBnx58TlsPrIxauKIFQTiyH+0MK4e97y4sV9ERbI+zDxw7i2hxHLCIEGIE/8PPvDxGhgzIOTSOWcs6/MQ==}
     engines: {node: '>=18'}
@@ -3577,6 +3618,9 @@ packages:
       '@types/react': '>=16'
       react: '>=16'
 
+  '@mermaid-js/parser@0.6.3':
+    resolution: {integrity: sha512-lnjOhe7zyHjc+If7yT4zoedx2vo4sHaTmtkl1+or8BRTnCtDmcTpAjpzDSfCZrshM5bCoz0GyidzadJAH1xobA==}
+
   '@microsoft/applicationinsights-web-snippet@1.0.1':
     resolution: {integrity: sha512-2IHAOaLauc8qaAitvWS+U931T+ze+7MNWrDHY47IENP5y2UA0vqJDu67kWZDdpCN1fFC77sfgfB+HV7SrKshnQ==}
 
@@ -4642,6 +4686,99 @@ packages:
   '@types/cookiejar@2.1.5':
     resolution: {integrity: sha512-he+DHOWReW0nghN24E1WUqM0efK4kI9oTqDm6XmK8ZPe2djZ90BSNdGnIyCLzCPw7/pogPlGbzI2wHGGmi4O/Q==}
 
+  '@types/d3-array@3.2.2':
+    resolution: {integrity: sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==}
+
+  '@types/d3-axis@3.0.6':
+    resolution: {integrity: sha512-pYeijfZuBd87T0hGn0FO1vQ/cgLk6E1ALJjfkC0oJ8cbwkZl3TpgS8bVBLZN+2jjGgg38epgxb2zmoGtSfvgMw==}
+
+  '@types/d3-brush@3.0.6':
+    resolution: {integrity: sha512-nH60IZNNxEcrh6L1ZSMNA28rj27ut/2ZmI3r96Zd+1jrZD++zD3LsMIjWlvg4AYrHn/Pqz4CF3veCxGjtbqt7A==}
+
+  '@types/d3-chord@3.0.6':
+    resolution: {integrity: sha512-LFYWWd8nwfwEmTZG9PfQxd17HbNPksHBiJHaKuY1XeqscXacsS2tyoo6OdRsjf+NQYeB6XrNL3a25E3gH69lcg==}
+
+  '@types/d3-color@3.1.3':
+    resolution: {integrity: sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==}
+
+  '@types/d3-contour@3.0.6':
+    resolution: {integrity: sha512-BjzLgXGnCWjUSYGfH1cpdo41/hgdWETu4YxpezoztawmqsvCeep+8QGfiY6YbDvfgHz/DkjeIkkZVJavB4a3rg==}
+
+  '@types/d3-delaunay@6.0.4':
+    resolution: {integrity: sha512-ZMaSKu4THYCU6sV64Lhg6qjf1orxBthaC161plr5KuPHo3CNm8DTHiLw/5Eq2b6TsNP0W0iJrUOFscY6Q450Hw==}
+
+  '@types/d3-dispatch@3.0.7':
+    resolution: {integrity: sha512-5o9OIAdKkhN1QItV2oqaE5KMIiXAvDWBDPrD85e58Qlz1c1kI/J0NcqbEG88CoTwJrYe7ntUCVfeUl2UJKbWgA==}
+
+  '@types/d3-drag@3.0.7':
+    resolution: {integrity: sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==}
+
+  '@types/d3-dsv@3.0.7':
+    resolution: {integrity: sha512-n6QBF9/+XASqcKK6waudgL0pf/S5XHPPI8APyMLLUHd8NqouBGLsU8MgtO7NINGtPBtk9Kko/W4ea0oAspwh9g==}
+
+  '@types/d3-ease@3.0.2':
+    resolution: {integrity: sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA==}
+
+  '@types/d3-fetch@3.0.7':
+    resolution: {integrity: sha512-fTAfNmxSb9SOWNB9IoG5c8Hg6R+AzUHDRlsXsDZsNp6sxAEOP0tkP3gKkNSO/qmHPoBFTxNrjDprVHDQDvo5aA==}
+
+  '@types/d3-force@3.0.10':
+    resolution: {integrity: sha512-ZYeSaCF3p73RdOKcjj+swRlZfnYpK1EbaDiYICEEp5Q6sUiqFaFQ9qgoshp5CzIyyb/yD09kD9o2zEltCexlgw==}
+
+  '@types/d3-format@3.0.4':
+    resolution: {integrity: sha512-fALi2aI6shfg7vM5KiR1wNJnZ7r6UuggVqtDA+xiEdPZQwy/trcQaHnwShLuLdta2rTymCNpxYTiMZX/e09F4g==}
+
+  '@types/d3-geo@3.1.0':
+    resolution: {integrity: sha512-856sckF0oP/diXtS4jNsiQw/UuK5fQG8l/a9VVLeSouf1/PPbBE1i1W852zVwKwYCBkFJJB7nCFTbk6UMEXBOQ==}
+
+  '@types/d3-hierarchy@3.1.7':
+    resolution: {integrity: sha512-tJFtNoYBtRtkNysX1Xq4sxtjK8YgoWUNpIiUee0/jHGRwqvzYxkq0hGVbbOGSz+JgFxxRu4K8nb3YpG3CMARtg==}
+
+  '@types/d3-interpolate@3.0.4':
+    resolution: {integrity: sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==}
+
+  '@types/d3-path@3.1.1':
+    resolution: {integrity: sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg==}
+
+  '@types/d3-polygon@3.0.2':
+    resolution: {integrity: sha512-ZuWOtMaHCkN9xoeEMr1ubW2nGWsp4nIql+OPQRstu4ypeZ+zk3YKqQT0CXVe/PYqrKpZAi+J9mTs05TKwjXSRA==}
+
+  '@types/d3-quadtree@3.0.6':
+    resolution: {integrity: sha512-oUzyO1/Zm6rsxKRHA1vH0NEDG58HrT5icx/azi9MF1TWdtttWl0UIUsjEQBBh+SIkrpd21ZjEv7ptxWys1ncsg==}
+
+  '@types/d3-random@3.0.3':
+    resolution: {integrity: sha512-Imagg1vJ3y76Y2ea0871wpabqp613+8/r0mCLEBfdtqC7xMSfj9idOnmBYyMoULfHePJyxMAw3nWhJxzc+LFwQ==}
+
+  '@types/d3-scale-chromatic@3.1.0':
+    resolution: {integrity: sha512-iWMJgwkK7yTRmWqRB5plb1kadXyQ5Sj8V/zYlFGMUBbIPKQScw+Dku9cAAMgJG+z5GYDoMjWGLVOvjghDEFnKQ==}
+
+  '@types/d3-scale@4.0.9':
+    resolution: {integrity: sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==}
+
+  '@types/d3-selection@3.0.11':
+    resolution: {integrity: sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==}
+
+  '@types/d3-shape@3.1.7':
+    resolution: {integrity: sha512-VLvUQ33C+3J+8p+Daf+nYSOsjB4GXp19/S/aGo60m9h1v6XaxjiT82lKVWJCfzhtuZ3yD7i/TPeC/fuKLLOSmg==}
+
+  '@types/d3-time-format@4.0.3':
+    resolution: {integrity: sha512-5xg9rC+wWL8kdDj153qZcsJ0FWiFt0J5RB6LYUNZjwSnesfblqrI/bJ1wBdJ8OQfncgbJG5+2F+qfqnqyzYxyg==}
+
+  '@types/d3-time@3.0.4':
+    resolution: {integrity: sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==}
+
+  '@types/d3-timer@3.0.2':
+    resolution: {integrity: sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==}
+
+  '@types/d3-transition@3.0.9':
+    resolution: {integrity: sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==}
+
+  '@types/d3-zoom@3.0.8':
+    resolution: {integrity: sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==}
+
+  '@types/d3@7.4.3':
+    resolution: {integrity: sha512-lZXZ9ckh5R8uiFVt8ogUNf+pIrK4EsWrx2Np75WvF/eTpJ0FMHNhjXk8CKEx/+gpHbNQyJWehbFaTvqmHWB3ww==}
+
   '@types/debug@4.1.12':
     resolution: {integrity: sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==}
 
@@ -4672,6 +4809,9 @@ packages:
   '@types/express@4.17.25':
     resolution: {integrity: sha512-dVd04UKsfpINUnK0yBoYHDF3xu7xVH4BuDotC/xGuycx4CgbP48X/KF/586bcObxT0HENHXEU8Nqtu6NR+eKhw==}
 
+  '@types/geojson@7946.0.16':
+    resolution: {integrity: sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==}
+
   '@types/graphql-depth-limit@1.1.6':
     resolution: {integrity: sha512-WU4bjoKOzJ8CQE32Pbyq+YshTMcLJf2aJuvVtSLv1BQPwDUGa38m2Vr8GGxf0GZ0luCQcfxlhZeHKu6nmTBvrw==}
 
@@ -4827,6 +4967,9 @@ packages:
   '@types/triple-beam@1.3.5':
     resolution: {integrity: sha512-6WaYesThRMCl19iryMYP7/x2OVgCtbIVflDGFpWnb9irXI3UjYE4AzmYuiUKY1AJstGijoY+MgUszMgRxIYTYw==}
 
+  '@types/trusted-types@2.0.7':
+    resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
+
   '@types/unist@2.0.11':
     resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
 
@@ -5645,6 +5788,14 @@ packages:
     resolution: {integrity: sha512-VqR8m68vM46BNnuZ5NtnGBKIE/DfN0cRIzg9n40EIq9NOv90ayxLBXA8fXC5gquFRGJSTRqBq25Jt2ECLR431Q==}
     engines: {node: '>= 6'}
 
+  chevrotain-allstar@0.3.1:
+    resolution: {integrity: sha512-b7g+y9A0v4mxCW1qUhf3BSVPg+/NvGErk/dOkrDaHA0nQIQGAtrOjlX//9OQtRlSCy+x9rfB5N8yC71lH1nvMw==}
+    peerDependencies:
+      chevrotain: ^11.0.0
+
+  chevrotain@11.0.3:
+    resolution: {integrity: sha512-ci2iJH6LeIkvP9eJW6gpueU8cnZhv85ELY8w8WiFtNjMHA5ad6pQLaJo9mEly/9qUyCpvqX8/POVUTf18/HFdw==}
+
   chokidar@3.6.0:
     resolution: {integrity: sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==}
     engines: {node: '>= 8.10.0'}
@@ -5845,6 +5996,9 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  confbox@0.1.8:
+    resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==}
+
   config-chain@1.1.13:
     resolution: {integrity: sha512-qj+f8APARXHrM0hraqXYb2/bOVSV4PvJQlNZ/DVj0QrmNM2q2euizkeuVckQ57J+W0mRH6Hvi+k50M4Jul2VRQ==}
 
@@ -5924,6 +6078,12 @@ packages:
     resolution: {integrity: sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g==}
     engines: {node: '>= 0.10'}
 
+  cose-base@1.0.3:
+    resolution: {integrity: sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==}
+
+  cose-base@2.2.0:
+    resolution: {integrity: sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==}
+
   cosmiconfig@8.3.6:
     resolution: {integrity: sha512-kcZ6+W5QzcJ3P1Mt+83OUv/oHFqZHIx8DuxG6eZ5RGMERoLqp4BuGjhHLYGK+Kf5XVkQvqBSmAy/nGWN3qDgEA==}
     engines: {node: '>=14'}
@@ -6088,6 +6248,162 @@ packages:
   cybersource-rest-client@0.0.73:
     resolution: {integrity: sha512-E9Wob960gV01W/fGj4SU5xC0rPVZJbshOsIYqkpfpRGLJIfwZp3gv/stW2F9XsWviRvZrp2S9c6TYtcP+4P1Hw==}
 
+  cytoscape-cose-bilkent@4.1.0:
+    resolution: {integrity: sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==}
+    peerDependencies:
+      cytoscape: ^3.2.0
+
+  cytoscape-fcose@2.2.0:
+    resolution: {integrity: sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ==}
+    peerDependencies:
+      cytoscape: ^3.2.0
+
+  cytoscape@3.33.1:
+    resolution: {integrity: sha512-iJc4TwyANnOGR1OmWhsS9ayRS3s+XQ185FmuHObThD+5AeJCakAAbWv8KimMTt08xCCLNgneQwFp+JRJOr9qGQ==}
+    engines: {node: '>=0.10'}
+
+  d3-array@2.12.1:
+    resolution: {integrity: sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ==}
+
+  d3-array@3.2.4:
+    resolution: {integrity: sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==}
+    engines: {node: '>=12'}
+
+  d3-axis@3.0.0:
+    resolution: {integrity: sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==}
+    engines: {node: '>=12'}
+
+  d3-brush@3.0.0:
+    resolution: {integrity: sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==}
+    engines: {node: '>=12'}
+
+  d3-chord@3.0.1:
+    resolution: {integrity: sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g==}
+    engines: {node: '>=12'}
+
+  d3-color@3.1.0:
+    resolution: {integrity: sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==}
+    engines: {node: '>=12'}
+
+  d3-contour@4.0.2:
+    resolution: {integrity: sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA==}
+    engines: {node: '>=12'}
+
+  d3-delaunay@6.0.4:
+    resolution: {integrity: sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A==}
+    engines: {node: '>=12'}
+
+  d3-dispatch@3.0.1:
+    resolution: {integrity: sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==}
+    engines: {node: '>=12'}
+
+  d3-drag@3.0.0:
+    resolution: {integrity: sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==}
+    engines: {node: '>=12'}
+
+  d3-dsv@3.0.1:
+    resolution: {integrity: sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q==}
+    engines: {node: '>=12'}
+    hasBin: true
+
+  d3-ease@3.0.1:
+    resolution: {integrity: sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==}
+    engines: {node: '>=12'}
+
+  d3-fetch@3.0.1:
+    resolution: {integrity: sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==}
+    engines: {node: '>=12'}
+
+  d3-force@3.0.0:
+    resolution: {integrity: sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==}
+    engines: {node: '>=12'}
+
+  d3-format@3.1.0:
+    resolution: {integrity: sha512-YyUI6AEuY/Wpt8KWLgZHsIU86atmikuoOmCfommt0LYHiQSPjvX2AcFc38PX0CBpr2RCyZhjex+NS/LPOv6YqA==}
+    engines: {node: '>=12'}
+
+  d3-geo@3.1.1:
+    resolution: {integrity: sha512-637ln3gXKXOwhalDzinUgY83KzNWZRKbYubaG+fGVuc/dxO64RRljtCTnf5ecMyE1RIdtqpkVcq0IbtU2S8j2Q==}
+    engines: {node: '>=12'}
+
+  d3-hierarchy@3.1.2:
+    resolution: {integrity: sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA==}
+    engines: {node: '>=12'}
+
+  d3-interpolate@3.0.1:
+    resolution: {integrity: sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==}
+    engines: {node: '>=12'}
+
+  d3-path@1.0.9:
+    resolution: {integrity: sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg==}
+
+  d3-path@3.1.0:
+    resolution: {integrity: sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==}
+    engines: {node: '>=12'}
+
+  d3-polygon@3.0.1:
+    resolution: {integrity: sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg==}
+    engines: {node: '>=12'}
+
+  d3-quadtree@3.0.1:
+    resolution: {integrity: sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==}
+    engines: {node: '>=12'}
+
+  d3-random@3.0.1:
+    resolution: {integrity: sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ==}
+    engines: {node: '>=12'}
+
+  d3-sankey@0.12.3:
+    resolution: {integrity: sha512-nQhsBRmM19Ax5xEIPLMY9ZmJ/cDvd1BG3UVvt5h3WRxKg5zGRbvnteTyWAbzeSvlh3tW7ZEmq4VwR5mB3tutmQ==}
+
+  d3-scale-chromatic@3.1.0:
+    resolution: {integrity: sha512-A3s5PWiZ9YCXFye1o246KoscMWqf8BsD9eRiJ3He7C9OBaxKhAd5TFCdEx/7VbKtxxTsu//1mMJFrEt572cEyQ==}
+    engines: {node: '>=12'}
+
+  d3-scale@4.0.2:
+    resolution: {integrity: sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==}
+    engines: {node: '>=12'}
+
+  d3-selection@3.0.0:
+    resolution: {integrity: sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==}
+    engines: {node: '>=12'}
+
+  d3-shape@1.3.7:
+    resolution: {integrity: sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw==}
+
+  d3-shape@3.2.0:
+    resolution: {integrity: sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==}
+    engines: {node: '>=12'}
+
+  d3-time-format@4.1.0:
+    resolution: {integrity: sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==}
+    engines: {node: '>=12'}
+
+  d3-time@3.1.0:
+    resolution: {integrity: sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==}
+    engines: {node: '>=12'}
+
+  d3-timer@3.0.1:
+    resolution: {integrity: sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==}
+    engines: {node: '>=12'}
+
+  d3-transition@3.0.1:
+    resolution: {integrity: sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==}
+    engines: {node: '>=12'}
+    peerDependencies:
+      d3-selection: 2 - 3
+
+  d3-zoom@3.0.0:
+    resolution: {integrity: sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==}
+    engines: {node: '>=12'}
+
+  d3@7.9.0:
+    resolution: {integrity: sha512-e1U46jVP+w7Iut8Jt8ri1YsPOvFpg46k+K8TpCb0P+zjCkjkPnV7WzfDJzMHy1LnA+wj5pLT1wjO901gLXeEhA==}
+    engines: {node: '>=12'}
+
+  dagre-d3-es@7.0.13:
+    resolution: {integrity: sha512-efEhnxpSuwpYOKRm/L5KbqoZmNNukHa/Flty4Wp62JRvgH2ojwVgPgdYyr4twpieZnyRDdIH7PY2mopX26+j2Q==}
+
   data-uri-to-buffer@4.0.1:
     resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==}
     engines: {node: '>= 12'}
@@ -6197,6 +6513,9 @@ packages:
     resolution: {integrity: sha512-8QmQKqEASLd5nx0U1B1okLElbUuuttJ/AnYmRXbbbGDWh6uS208EjD4Xqq/I9wK7u0v6O08XhTWnt5XtEbR6Dg==}
     engines: {node: '>= 0.4'}
 
+  delaunator@5.0.1:
+    resolution: {integrity: sha512-8nvh+XBe96aCESrGOqMp/84b13H9cdKbG5P2ejQCh4d4sK9RL4371qou9drQjMhvnPmhWl5hnmqbEE0fXr9Xnw==}
+
   delayed-stream@1.0.0:
     resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==}
     engines: {node: '>=0.4.0'}
@@ -6306,6 +6625,9 @@ packages:
     resolution: {integrity: sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==}
     engines: {node: '>= 4'}
 
+  dompurify@3.3.1:
+    resolution: {integrity: sha512-qkdCKzLNtrgPFP1Vo+98FRzJnBRGe4ffyCea9IwHB1fyxPOeNTHpLKYGd4Uk9xvNoH0ZoOjwZxNptyMwqrId1Q==}
+
   domutils@2.8.0:
     resolution: {integrity: sha512-w96Cjofp72M5IIhpjgobBimYEfoPjx1Vx0BSX9P30WBdZW2WIKU0T1Bd0kz2eNZ9ikjKgHbEyKx8BB6H1L3h3A==}
 
@@ -7077,6 +7399,9 @@ packages:
     resolution: {integrity: sha512-ax7ZYomf6jqPTQ4+XCpUGyXKHk5WweS+e05MBO4/y3WJ5RkmPXNKvX+bx1behVILVwr6JSQvZAku021CHPXG3Q==}
     engines: {node: '>=10'}
 
+  hachure-fill@0.5.2:
+    resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==}
+
   handle-thing@2.0.1:
     resolution: {integrity: sha512-9Qn4yBxelxoh2Ow62nP+Ka/kMnOXRi8BXnRaUwezLNhqelnN49xKz4F/dPP8OYLxLxq6JDtZb2i9XznUQbNPTg==}
 
@@ -7387,6 +7712,13 @@ packages:
     resolution: {integrity: sha512-4gd7VpWNQNB4UKKCFFVcp1AVv+FMOgs9NKzjHKusc8jTMhd5eL1NqQqOpE0KzMds804/yHlglp3uxgluOqAPLw==}
     engines: {node: '>= 0.4'}
 
+  internmap@1.0.1:
+    resolution: {integrity: sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==}
+
+  internmap@2.0.3:
+    resolution: {integrity: sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==}
+    engines: {node: '>=12'}
+
   invariant@2.2.4:
     resolution: {integrity: sha512-phJfQVBuaJM5raOpJjSfkiD6BpbCE4Ns//LaXl6wGYtUBY83nWS6Rf9tXm2e8VaK60JEjYldbPif/A2B1C2gNA==}
 
@@ -7825,9 +8157,16 @@ packages:
     resolution: {integrity: sha512-C3iHfuGUXK2u8/ipq9LfjFfXFxAZMQJJq7vLS45r3D9Y2xQ/m4S8zaR4zMLFWh9AsNPXmcFfUDhTEO8UIC/V6Q==}
     engines: {node: '>=12.0.0'}
 
+  katex@0.16.27:
+    resolution: {integrity: sha512-aeQoDkuRWSqQN6nSvVCEFvfXdqo1OQiCmmW1kc9xSdjutPv7BGO7pqY9sQRJpMOGrEdfDgF2TfRXe5eUAD2Waw==}
+    hasBin: true
+
   keyv@4.5.4:
     resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
 
+  khroma@2.1.0:
+    resolution: {integrity: sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw==}
+
   kind-of@6.0.3:
     resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==}
     engines: {node: '>=0.10.0'}
@@ -7850,6 +8189,10 @@ packages:
   kuler@2.0.0:
     resolution: {integrity: sha512-Xq9nH7KlWZmXAtodXDDRE7vs6DU1gTU8zYDHDiWLSip45Egwq3plLHzPn27NgvzL2r1LMPC1vdqh98sQxtqj4A==}
 
+  langium@3.3.1:
+    resolution: {integrity: sha512-QJv/h939gDpvT+9SiLVlY7tZC3xB2qK57v0J04Sh9wpMb6MP1q8gB21L3WIo8T5P1MSMg3Ep14L7KkDCFG3y4w==}
+    engines: {node: '>=16.0.0'}
+
   latest-version@7.0.0:
     resolution: {integrity: sha512-KvNT4XqAMzdcL6ka6Tl3i2lYeFDgXNCuIX+xNx6ZMVR1dFq+idXd9FLKNMOIx0t9mJ9/HudyX4oZWXZQ0UJHeg==}
     engines: {node: '>=14.16'}
@@ -7857,6 +8200,12 @@ packages:
   launch-editor@2.12.0:
     resolution: {integrity: sha512-giOHXoOtifjdHqUamwKq6c49GzBdLjvxrd2D+Q4V6uOHopJv7p9VJxikDsQ/CBXZbEITgUqSVHXLTG3VhPP1Dg==}
 
+  layout-base@1.0.2:
+    resolution: {integrity: sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==}
+
+  layout-base@2.0.1:
+    resolution: {integrity: sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg==}
+
   leven@2.1.0:
     resolution: {integrity: sha512-nvVPLpIHUxCUoRLrFqTgSxXJ614d8AgQoWl7zPe/2VadE8+1dpU3LBhowRuBAcuwruWtOdD8oYC9jDNJjXDPyA==}
     engines: {node: '>=0.10.0'}
@@ -7981,6 +8330,12 @@ packages:
     resolution: {integrity: sha512-gvVijfZvn7R+2qyPX8mAuKcFGDf6Nc61GdvGafQsHL0sBIxfKzA+usWn4GFC/bk+QdwPUD4kWFJLhElipq+0VA==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
 
+  lodash-es@4.17.21:
+    resolution: {integrity: sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==}
+
+  lodash-es@4.17.22:
+    resolution: {integrity: sha512-XEawp1t0gxSi9x01glktRZ5HDy0HXqrM0x5pXQM98EaI0NxO6jVM7omDOxsuEo5UIASAnm2bRp1Jt/e0a2XU8Q==}
+
   lodash.camelcase@4.3.0:
     resolution: {integrity: sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==}
 
@@ -8134,6 +8489,11 @@ packages:
   markdown-table@3.0.4:
     resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
 
+  marked@16.4.2:
+    resolution: {integrity: sha512-TI3V8YYWvkVf3KJe1dRkpnjs68JUPyEa5vjKrp1XEEJUAOaQc+Qj+L1qWbPd0SJuAdQkFU0h73sXXqwDYxsiDA==}
+    engines: {node: '>= 20'}
+    hasBin: true
+
   matcher@3.0.0:
     resolution: {integrity: sha512-OkeDaAZ/bQCxeFAozM55PKcKU0yJMPGifLwV4Qgjitu+5MoAfSQN4lsLJeXZ1b8w0x+/Emda6MZgXS1jvsapng==}
     engines: {node: '>=10'}
@@ -8229,6 +8589,9 @@ packages:
     resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
     engines: {node: '>= 8'}
 
+  mermaid@11.12.2:
+    resolution: {integrity: sha512-n34QPDPEKmaeCG4WDMGy0OT6PSyxKCfy2pJgShP+Qow2KLrvWjclwbc3yXfSIf4BanqWEhQEpngWwNp/XhZt6w==}
+
   meros@1.3.2:
     resolution: {integrity: sha512-Q3mobPbvEx7XbwhnC1J1r60+5H6EZyNccdzSz0eGexJRwouUtTZxPVRGdqKtxlpD84ScK4+tIGldkqDtCKdI0A==}
     engines: {node: '>=13'}
@@ -8461,6 +8824,9 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
+  mlly@1.8.0:
+    resolution: {integrity: sha512-l8D9ODSRWLe2KHJSifWGwBqpTZXIXTeo8mlKjY+E2HAakaTeNpqAyBZ8GSqLzHgw4XmHmC8whvpjJNMbFZN7/g==}
+
   module-details-from-path@1.0.4:
     resolution: {integrity: sha512-EGWKgxALGMgzvxYF1UyGTy0HXX/2vHLkw6+NvDKW2jypWbHpjQuj4UMcqQWXHERJhVGKikolT06G3bcKe4fi7w==}
 
@@ -8843,6 +9209,9 @@ packages:
     resolution: {integrity: sha512-cbH9IAIJHNj9uXi196JVsRlt7cHKak6u/e6AkL/bkRelZ7rlL3X1YKxsZwa36xipOEKAsdtmaG6aAJoM1fx2zA==}
     engines: {node: '>=14.16'}
 
+  package-manager-detector@1.6.0:
+    resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
+
   pad-right@0.2.2:
     resolution: {integrity: sha512-4cy8M95ioIGolCoMmm2cMntGR1lPLEbOMzOKu8bzjuJP6JpzEMQcDHmh7hHLYGgob+nKe1YHFMaG4V59HQa89g==}
     engines: {node: '>=0.10.0'}
@@ -8897,6 +9266,9 @@ packages:
   path-case@3.0.4:
     resolution: {integrity: sha512-qO4qCFjXqVTrcbPt/hQfhTQ+VhFsqNKOPtytgNKkKxSoEp3XPUQ8ObFuePylOIok5gjn69ry8XiULxCwot3Wfg==}
 
+  path-data-parser@0.1.0:
+    resolution: {integrity: sha512-NOnmBpt5Y2RWbuv0LMzsayp3lVylAHLPUTut412ZA3l+C4uw4ZVkQbjShYCQ8TCpUMdPapr4YjUqLYD6v68j+w==}
+
   path-exists@4.0.0:
     resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
     engines: {node: '>=8'}
@@ -8990,6 +9362,9 @@ packages:
     resolution: {integrity: sha512-Ie9z/WINcxxLp27BKOCHGde4ITq9UklYKDzVo1nhk5sqGEXU3FpkwP5GM2voTGJkGd9B3Otl+Q4uwSOeSUtOBA==}
     engines: {node: '>=14.16'}
 
+  pkg-types@1.3.1:
+    resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
+
   playwright-core@1.56.1:
     resolution: {integrity: sha512-hutraynyn31F+Bifme+Ps9Vq59hKuUCz7H1kDOcBs+2oGguKkWTU50bBWrtz34OUWmIwpBTWDxaRPXrIXkgvmQ==}
     engines: {node: '>=18'}
@@ -9000,6 +9375,12 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  points-on-curve@0.2.0:
+    resolution: {integrity: sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==}
+
+  points-on-path@0.2.1:
+    resolution: {integrity: sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g==}
+
   possible-typed-array-names@1.1.0:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
@@ -10068,6 +10449,9 @@ packages:
     resolution: {integrity: sha512-CHhPh+UNHD2GTXNYhPWLnU8ONHdI+5DI+4EYIAOaiD63rHeYlZvyh8P+in5999TTSFgUYuKUAjzRI4mdh/p+2A==}
     engines: {node: '>=8.0'}
 
+  robust-predicates@3.0.2:
+    resolution: {integrity: sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg==}
+
   rollup@3.29.4:
     resolution: {integrity: sha512-oWzmBZwvYrU0iJHtDmhsm662rC15FRXmcjCk1xD771dFDx5jJ02ufAQQTn0etB2emNk4J9EZg/yWKpsn9BWGRw==}
     engines: {node: '>=14.18.0', npm: '>=8.0.0'}
@@ -10078,6 +10462,9 @@ packages:
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
     hasBin: true
 
+  roughjs@4.6.6:
+    resolution: {integrity: sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ==}
+
   rrweb-cssom@0.8.0:
     resolution: {integrity: sha512-guoltQEx+9aMf2gDZ0s62EcV8lsXR+0w8915TC3ITdn2YueuNjdAYh/levpU9nFaoChh9RUS5ZdQMrKfVEN9tw==}
 
@@ -10097,6 +10484,9 @@ packages:
   run-parallel@1.2.0:
     resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
 
+  rw@1.3.3:
+    resolution: {integrity: sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==}
+
   rxjs@7.8.2:
     resolution: {integrity: sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==}
 
@@ -10769,6 +11159,10 @@ packages:
   tinyexec@0.3.2:
     resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==}
 
+  tinyexec@1.0.2:
+    resolution: {integrity: sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==}
+    engines: {node: '>=18'}
+
   tinyglobby@0.2.15:
     resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
     engines: {node: '>=12.0.0'}
@@ -11057,6 +11451,9 @@ packages:
     resolution: {integrity: sha512-LbBDqdIC5s8iROCUjMbW1f5dJQTEFB1+KO9ogbvlb3nm9n4YHa5p4KTvFPWvh2Hs8gZMBuiB1/8+pdfe/tDPug==}
     hasBin: true
 
+  ufo@1.6.1:
+    resolution: {integrity: sha512-9a4/uxlTWJ4+a5i0ooc1rU7C7YOw3wT+UGqdeNNHWnOF9qcMBgLRS+4IYUqbczewFx4mLEig6gawh7X6mFlEkA==}
+
   unbox-primitive@1.1.0:
     resolution: {integrity: sha512-nWJ91DjeOkej/TA8pXQ3myruKpKEYgqvpw9lz4OPHj/NWFNluYrjbz9j01CJ8yKQd2g4jFoOkINCTW2I5LEEyw==}
     engines: {node: '>= 0.4'}
@@ -11339,6 +11736,26 @@ packages:
       jsdom:
         optional: true
 
+  vscode-jsonrpc@8.2.0:
+    resolution: {integrity: sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==}
+    engines: {node: '>=14.0.0'}
+
+  vscode-languageserver-protocol@3.17.5:
+    resolution: {integrity: sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==}
+
+  vscode-languageserver-textdocument@1.0.12:
+    resolution: {integrity: sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==}
+
+  vscode-languageserver-types@3.17.5:
+    resolution: {integrity: sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==}
+
+  vscode-languageserver@9.0.1:
+    resolution: {integrity: sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==}
+    hasBin: true
+
+  vscode-uri@3.0.8:
+    resolution: {integrity: sha512-AyFQ0EVmsOZOlAnxoFOGOq1SQDWAB7C6aqMGS23svWAllfOaxbuFvcT8D1i8z3Gyn8fraVeZNNmN6e9bxxXkKw==}
+
   w3c-xmlserializer@5.0.0:
     resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==}
     engines: {node: '>=18'}
@@ -11852,6 +12269,11 @@ snapshots:
       react: 19.2.0
       react-dom: 19.2.0(react@19.2.0)
 
+  '@antfu/install-pkg@1.1.0':
+    dependencies:
+      package-manager-detector: 1.6.0
+      tinyexec: 1.0.2
+
   '@apollo/cache-control-types@1.0.3(graphql@16.11.0)':
     dependencies:
       graphql: 16.11.0
@@ -13039,6 +13461,25 @@ snapshots:
   '@biomejs/cli-win32-x64@2.0.0':
     optional: true
 
+  '@braintree/sanitize-url@7.1.1': {}
+
+  '@chevrotain/cst-dts-gen@11.0.3':
+    dependencies:
+      '@chevrotain/gast': 11.0.3
+      '@chevrotain/types': 11.0.3
+      lodash-es: 4.17.21
+
+  '@chevrotain/gast@11.0.3':
+    dependencies:
+      '@chevrotain/types': 11.0.3
+      lodash-es: 4.17.21
+
+  '@chevrotain/regexp-to-ast@11.0.3': {}
+
+  '@chevrotain/types@11.0.3': {}
+
+  '@chevrotain/utils@11.0.3': {}
+
   '@chromatic-com/storybook@4.1.2(storybook@9.1.16(@testing-library/dom@10.4.1)(vite@7.1.12(@types/node@24.9.2)(jiti@2.6.1)(lightningcss@1.30.2)(terser@5.44.0)(tsx@4.20.6)(yaml@2.8.1)))':
     dependencies:
       '@neoconfetti/react': 1.0.0
@@ -14126,6 +14567,36 @@ snapshots:
       - uglify-js
       - webpack-cli
 
+  '@docusaurus/theme-mermaid@3.9.2(@docusaurus/plugin-content-docs@3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3))(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3)':
+    dependencies:
+      '@docusaurus/core': 3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3)
+      '@docusaurus/module-type-aliases': 3.9.2(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
+      '@docusaurus/theme-common': 3.9.2(@docusaurus/plugin-content-docs@3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3))(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
+      '@docusaurus/types': 3.9.2(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
+      '@docusaurus/utils-validation': 3.9.2(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
+      mermaid: 11.12.2
+      react: 19.2.0
+      react-dom: 19.2.0(react@19.2.0)
+      tslib: 2.8.1
+    transitivePeerDependencies:
+      - '@docusaurus/faster'
+      - '@docusaurus/plugin-content-docs'
+      - '@mdx-js/react'
+      - '@parcel/css'
+      - '@rspack/core'
+      - '@swc/core'
+      - '@swc/css'
+      - bufferutil
+      - csso
+      - debug
+      - esbuild
+      - lightningcss
+      - supports-color
+      - typescript
+      - uglify-js
+      - utf-8-validate
+      - webpack-cli
+
   '@docusaurus/theme-search-algolia@3.9.2(@algolia/client-search@5.41.0)(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(@types/react@19.2.2)(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(search-insights@2.17.3)(typescript@5.6.3)':
     dependencies:
       '@docsearch/react': 3.9.0(@algolia/client-search@5.41.0)(@types/react@19.2.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(search-insights@2.17.3)
@@ -14975,6 +15446,14 @@ snapshots:
 
   '@humanwhocodes/retry@0.4.3': {}
 
+  '@iconify/types@2.0.0': {}
+
+  '@iconify/utils@3.1.0':
+    dependencies:
+      '@antfu/install-pkg': 1.1.0
+      '@iconify/types': 2.0.0
+      mlly: 1.8.0
+
   '@inquirer/external-editor@1.0.2(@types/node@24.9.2)':
     dependencies:
       chardet: 2.1.0
@@ -15130,6 +15609,10 @@ snapshots:
       '@types/react': 19.2.2
       react: 19.2.0
 
+  '@mermaid-js/parser@0.6.3':
+    dependencies:
+      langium: 3.3.1
+
   '@microsoft/applicationinsights-web-snippet@1.0.1': {}
 
   '@mongodb-js/saslprep@1.3.2':
@@ -16285,6 +16768,123 @@ snapshots:
 
   '@types/cookiejar@2.1.5': {}
 
+  '@types/d3-array@3.2.2': {}
+
+  '@types/d3-axis@3.0.6':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-brush@3.0.6':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-chord@3.0.6': {}
+
+  '@types/d3-color@3.1.3': {}
+
+  '@types/d3-contour@3.0.6':
+    dependencies:
+      '@types/d3-array': 3.2.2
+      '@types/geojson': 7946.0.16
+
+  '@types/d3-delaunay@6.0.4': {}
+
+  '@types/d3-dispatch@3.0.7': {}
+
+  '@types/d3-drag@3.0.7':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-dsv@3.0.7': {}
+
+  '@types/d3-ease@3.0.2': {}
+
+  '@types/d3-fetch@3.0.7':
+    dependencies:
+      '@types/d3-dsv': 3.0.7
+
+  '@types/d3-force@3.0.10': {}
+
+  '@types/d3-format@3.0.4': {}
+
+  '@types/d3-geo@3.1.0':
+    dependencies:
+      '@types/geojson': 7946.0.16
+
+  '@types/d3-hierarchy@3.1.7': {}
+
+  '@types/d3-interpolate@3.0.4':
+    dependencies:
+      '@types/d3-color': 3.1.3
+
+  '@types/d3-path@3.1.1': {}
+
+  '@types/d3-polygon@3.0.2': {}
+
+  '@types/d3-quadtree@3.0.6': {}
+
+  '@types/d3-random@3.0.3': {}
+
+  '@types/d3-scale-chromatic@3.1.0': {}
+
+  '@types/d3-scale@4.0.9':
+    dependencies:
+      '@types/d3-time': 3.0.4
+
+  '@types/d3-selection@3.0.11': {}
+
+  '@types/d3-shape@3.1.7':
+    dependencies:
+      '@types/d3-path': 3.1.1
+
+  '@types/d3-time-format@4.0.3': {}
+
+  '@types/d3-time@3.0.4': {}
+
+  '@types/d3-timer@3.0.2': {}
+
+  '@types/d3-transition@3.0.9':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-zoom@3.0.8':
+    dependencies:
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3@7.4.3':
+    dependencies:
+      '@types/d3-array': 3.2.2
+      '@types/d3-axis': 3.0.6
+      '@types/d3-brush': 3.0.6
+      '@types/d3-chord': 3.0.6
+      '@types/d3-color': 3.1.3
+      '@types/d3-contour': 3.0.6
+      '@types/d3-delaunay': 6.0.4
+      '@types/d3-dispatch': 3.0.7
+      '@types/d3-drag': 3.0.7
+      '@types/d3-dsv': 3.0.7
+      '@types/d3-ease': 3.0.2
+      '@types/d3-fetch': 3.0.7
+      '@types/d3-force': 3.0.10
+      '@types/d3-format': 3.0.4
+      '@types/d3-geo': 3.1.0
+      '@types/d3-hierarchy': 3.1.7
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-path': 3.1.1
+      '@types/d3-polygon': 3.0.2
+      '@types/d3-quadtree': 3.0.6
+      '@types/d3-random': 3.0.3
+      '@types/d3-scale': 4.0.9
+      '@types/d3-scale-chromatic': 3.1.0
+      '@types/d3-selection': 3.0.11
+      '@types/d3-shape': 3.1.7
+      '@types/d3-time': 3.0.4
+      '@types/d3-time-format': 4.0.3
+      '@types/d3-timer': 3.0.2
+      '@types/d3-transition': 3.0.9
+      '@types/d3-zoom': 3.0.8
+
   '@types/debug@4.1.12':
     dependencies:
       '@types/ms': 2.1.0
@@ -16330,6 +16930,8 @@ snapshots:
       '@types/qs': 6.14.0
       '@types/serve-static': 1.15.10
 
+  '@types/geojson@7946.0.16': {}
+
   '@types/graphql-depth-limit@1.1.6':
     dependencies:
       graphql: 14.7.0
@@ -16495,6 +17097,9 @@ snapshots:
 
   '@types/triple-beam@1.3.5': {}
 
+  '@types/trusted-types@2.0.7':
+    optional: true
+
   '@types/unist@2.0.11': {}
 
   '@types/unist@3.0.3': {}
@@ -17627,6 +18232,20 @@ snapshots:
       parse5: 7.3.0
       parse5-htmlparser2-tree-adapter: 7.1.0
 
+  chevrotain-allstar@0.3.1(chevrotain@11.0.3):
+    dependencies:
+      chevrotain: 11.0.3
+      lodash-es: 4.17.22
+
+  chevrotain@11.0.3:
+    dependencies:
+      '@chevrotain/cst-dts-gen': 11.0.3
+      '@chevrotain/gast': 11.0.3
+      '@chevrotain/regexp-to-ast': 11.0.3
+      '@chevrotain/types': 11.0.3
+      '@chevrotain/utils': 11.0.3
+      lodash-es: 4.17.21
+
   chokidar@3.6.0:
     dependencies:
       anymatch: 3.1.3
@@ -17796,6 +18415,8 @@ snapshots:
       tree-kill: 1.2.2
       yargs: 17.7.2
 
+  confbox@0.1.8: {}
+
   config-chain@1.1.13:
     dependencies:
       ini: 1.3.8
@@ -17873,6 +18494,14 @@ snapshots:
       object-assign: 4.1.1
       vary: 1.1.2
 
+  cose-base@1.0.3:
+    dependencies:
+      layout-base: 1.0.2
+
+  cose-base@2.2.0:
+    dependencies:
+      layout-base: 2.0.1
+
   cosmiconfig@8.3.6(typescript@5.6.3):
     dependencies:
       import-fresh: 3.3.1
@@ -18101,6 +18730,190 @@ snapshots:
       - supports-color
       - undici
 
+  cytoscape-cose-bilkent@4.1.0(cytoscape@3.33.1):
+    dependencies:
+      cose-base: 1.0.3
+      cytoscape: 3.33.1
+
+  cytoscape-fcose@2.2.0(cytoscape@3.33.1):
+    dependencies:
+      cose-base: 2.2.0
+      cytoscape: 3.33.1
+
+  cytoscape@3.33.1: {}
+
+  d3-array@2.12.1:
+    dependencies:
+      internmap: 1.0.1
+
+  d3-array@3.2.4:
+    dependencies:
+      internmap: 2.0.3
+
+  d3-axis@3.0.0: {}
+
+  d3-brush@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
+  d3-chord@3.0.1:
+    dependencies:
+      d3-path: 3.1.0
+
+  d3-color@3.1.0: {}
+
+  d3-contour@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-delaunay@6.0.4:
+    dependencies:
+      delaunator: 5.0.1
+
+  d3-dispatch@3.0.1: {}
+
+  d3-drag@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-selection: 3.0.0
+
+  d3-dsv@3.0.1:
+    dependencies:
+      commander: 7.2.0
+      iconv-lite: 0.6.3
+      rw: 1.3.3
+
+  d3-ease@3.0.1: {}
+
+  d3-fetch@3.0.1:
+    dependencies:
+      d3-dsv: 3.0.1
+
+  d3-force@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-timer: 3.0.1
+
+  d3-format@3.1.0: {}
+
+  d3-geo@3.1.1:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-hierarchy@3.1.2: {}
+
+  d3-interpolate@3.0.1:
+    dependencies:
+      d3-color: 3.1.0
+
+  d3-path@1.0.9: {}
+
+  d3-path@3.1.0: {}
+
+  d3-polygon@3.0.1: {}
+
+  d3-quadtree@3.0.1: {}
+
+  d3-random@3.0.1: {}
+
+  d3-sankey@0.12.3:
+    dependencies:
+      d3-array: 2.12.1
+      d3-shape: 1.3.7
+
+  d3-scale-chromatic@3.1.0:
+    dependencies:
+      d3-color: 3.1.0
+      d3-interpolate: 3.0.1
+
+  d3-scale@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+      d3-format: 3.1.0
+      d3-interpolate: 3.0.1
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+
+  d3-selection@3.0.0: {}
+
+  d3-shape@1.3.7:
+    dependencies:
+      d3-path: 1.0.9
+
+  d3-shape@3.2.0:
+    dependencies:
+      d3-path: 3.1.0
+
+  d3-time-format@4.1.0:
+    dependencies:
+      d3-time: 3.1.0
+
+  d3-time@3.1.0:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-timer@3.0.1: {}
+
+  d3-transition@3.0.1(d3-selection@3.0.0):
+    dependencies:
+      d3-color: 3.1.0
+      d3-dispatch: 3.0.1
+      d3-ease: 3.0.1
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-timer: 3.0.1
+
+  d3-zoom@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
+  d3@7.9.0:
+    dependencies:
+      d3-array: 3.2.4
+      d3-axis: 3.0.0
+      d3-brush: 3.0.0
+      d3-chord: 3.0.1
+      d3-color: 3.1.0
+      d3-contour: 4.0.2
+      d3-delaunay: 6.0.4
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-dsv: 3.0.1
+      d3-ease: 3.0.1
+      d3-fetch: 3.0.1
+      d3-force: 3.0.0
+      d3-format: 3.1.0
+      d3-geo: 3.1.1
+      d3-hierarchy: 3.1.2
+      d3-interpolate: 3.0.1
+      d3-path: 3.1.0
+      d3-polygon: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-random: 3.0.1
+      d3-scale: 4.0.2
+      d3-scale-chromatic: 3.1.0
+      d3-selection: 3.0.0
+      d3-shape: 3.2.0
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+      d3-timer: 3.0.1
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+      d3-zoom: 3.0.0
+
+  dagre-d3-es@7.0.13:
+    dependencies:
+      d3: 7.9.0
+      lodash-es: 4.17.22
+
   data-uri-to-buffer@4.0.1: {}
 
   data-urls@5.0.0:
@@ -18195,6 +19008,10 @@ snapshots:
       has-property-descriptors: 1.0.2
       object-keys: 1.1.1
 
+  delaunator@5.0.1:
+    dependencies:
+      robust-predicates: 3.0.2
+
   delayed-stream@1.0.0: {}
 
   denque@2.1.0: {}
@@ -18288,6 +19105,10 @@ snapshots:
     dependencies:
       domelementtype: 2.3.0
 
+  dompurify@3.3.1:
+    optionalDependencies:
+      '@types/trusted-types': 2.0.7
+
   domutils@2.8.0:
     dependencies:
       dom-serializer: 1.4.1
@@ -19286,6 +20107,8 @@ snapshots:
     dependencies:
       duplexer: 0.1.2
 
+  hachure-fill@0.5.2: {}
+
   handle-thing@2.0.1: {}
 
   has-ansi@4.0.1:
@@ -19684,6 +20507,10 @@ snapshots:
       hasown: 2.0.2
       side-channel: 1.1.0
 
+  internmap@1.0.1: {}
+
+  internmap@2.0.3: {}
+
   invariant@2.2.4:
     dependencies:
       loose-envify: 1.4.0
@@ -20128,10 +20955,16 @@ snapshots:
 
   kareem@2.6.3: {}
 
+  katex@0.16.27:
+    dependencies:
+      commander: 8.3.0
+
   keyv@4.5.4:
     dependencies:
       json-buffer: 3.0.1
 
+  khroma@2.1.0: {}
+
   kind-of@6.0.3: {}
 
   kleur@3.0.3: {}
@@ -20159,6 +20992,14 @@ snapshots:
 
   kuler@2.0.0: {}
 
+  langium@3.3.1:
+    dependencies:
+      chevrotain: 11.0.3
+      chevrotain-allstar: 0.3.1(chevrotain@11.0.3)
+      vscode-languageserver: 9.0.1
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-uri: 3.0.8
+
   latest-version@7.0.0:
     dependencies:
       package-json: 8.1.1
@@ -20168,6 +21009,10 @@ snapshots:
       picocolors: 1.1.1
       shell-quote: 1.8.3
 
+  layout-base@1.0.2: {}
+
+  layout-base@2.0.1: {}
+
   leven@2.1.0: {}
 
   leven@3.1.0: {}
@@ -20270,6 +21115,10 @@ snapshots:
     dependencies:
       p-locate: 6.0.0
 
+  lodash-es@4.17.21: {}
+
+  lodash-es@4.17.22: {}
+
   lodash.camelcase@4.3.0: {}
 
   lodash.debounce@4.0.8: {}
@@ -20399,6 +21248,8 @@ snapshots:
 
   markdown-table@3.0.4: {}
 
+  marked@16.4.2: {}
+
   matcher@3.0.0:
     dependencies:
       escape-string-regexp: 4.0.0
@@ -20620,6 +21471,29 @@ snapshots:
 
   merge2@1.4.1: {}
 
+  mermaid@11.12.2:
+    dependencies:
+      '@braintree/sanitize-url': 7.1.1
+      '@iconify/utils': 3.1.0
+      '@mermaid-js/parser': 0.6.3
+      '@types/d3': 7.4.3
+      cytoscape: 3.33.1
+      cytoscape-cose-bilkent: 4.1.0(cytoscape@3.33.1)
+      cytoscape-fcose: 2.2.0(cytoscape@3.33.1)
+      d3: 7.9.0
+      d3-sankey: 0.12.3
+      dagre-d3-es: 7.0.13
+      dayjs: 1.11.18
+      dompurify: 3.3.1
+      katex: 0.16.27
+      khroma: 2.1.0
+      lodash-es: 4.17.22
+      marked: 16.4.2
+      roughjs: 4.6.6
+      stylis: 4.3.6
+      ts-dedent: 2.2.0
+      uuid: 11.1.0
+
   meros@1.3.2(@types/node@24.9.2):
     optionalDependencies:
       '@types/node': 24.9.2
@@ -20986,6 +21860,13 @@ snapshots:
 
   mkdirp@2.1.6: {}
 
+  mlly@1.8.0:
+    dependencies:
+      acorn: 8.15.0
+      pathe: 2.0.3
+      pkg-types: 1.3.1
+      ufo: 1.6.1
+
   module-details-from-path@1.0.4: {}
 
   moment-timezone@0.5.48:
@@ -21411,6 +22292,8 @@ snapshots:
       registry-url: 6.0.1
       semver: 7.7.3
 
+  package-manager-detector@1.6.0: {}
+
   pad-right@0.2.2:
     dependencies:
       repeat-string: 1.6.1
@@ -21482,6 +22365,8 @@ snapshots:
       dot-case: 3.0.4
       tslib: 2.8.1
 
+  path-data-parser@0.1.0: {}
+
   path-exists@4.0.0: {}
 
   path-exists@5.0.0: {}
@@ -21550,6 +22435,12 @@ snapshots:
     dependencies:
       find-up: 6.3.0
 
+  pkg-types@1.3.1:
+    dependencies:
+      confbox: 0.1.8
+      mlly: 1.8.0
+      pathe: 2.0.3
+
   playwright-core@1.56.1: {}
 
   playwright@1.56.1:
@@ -21558,6 +22449,13 @@ snapshots:
     optionalDependencies:
       fsevents: 2.3.2
 
+  points-on-curve@0.2.0: {}
+
+  points-on-path@0.2.1:
+    dependencies:
+      path-data-parser: 0.1.0
+      points-on-curve: 0.2.0
+
   possible-typed-array-names@1.1.0: {}
 
   postcss-attribute-case-insensitive@7.0.1(postcss@8.5.6):
@@ -22871,6 +23769,8 @@ snapshots:
       semver-compare: 1.0.0
       sprintf-js: 1.1.3
 
+  robust-predicates@3.0.2: {}
+
   rollup@3.29.4:
     optionalDependencies:
       fsevents: 2.3.3
@@ -22903,6 +23803,13 @@ snapshots:
       '@rollup/rollup-win32-x64-msvc': 4.52.5
       fsevents: 2.3.3
 
+  roughjs@4.6.6:
+    dependencies:
+      hachure-fill: 0.5.2
+      path-data-parser: 0.1.0
+      points-on-curve: 0.2.0
+      points-on-path: 0.2.1
+
   rrweb-cssom@0.8.0: {}
 
   rtlcss@4.3.0:
@@ -22920,6 +23827,8 @@ snapshots:
     dependencies:
       queue-microtask: 1.2.3
 
+  rw@1.3.3: {}
+
   rxjs@7.8.2:
     dependencies:
       tslib: 2.8.1
@@ -23654,6 +24563,8 @@ snapshots:
 
   tinyexec@0.3.2: {}
 
+  tinyexec@1.0.2: {}
+
   tinyglobby@0.2.15:
     dependencies:
       fdir: 6.5.0(picomatch@4.0.3)
@@ -23943,6 +24854,8 @@ snapshots:
 
   ua-parser-js@1.0.41: {}
 
+  ufo@1.6.1: {}
+
   unbox-primitive@1.1.0:
     dependencies:
       call-bound: 1.0.4
@@ -24306,6 +25219,23 @@ snapshots:
       - tsx
       - yaml
 
+  vscode-jsonrpc@8.2.0: {}
+
+  vscode-languageserver-protocol@3.17.5:
+    dependencies:
+      vscode-jsonrpc: 8.2.0
+      vscode-languageserver-types: 3.17.5
+
+  vscode-languageserver-textdocument@1.0.12: {}
+
+  vscode-languageserver-types@3.17.5: {}
+
+  vscode-languageserver@9.0.1:
+    dependencies:
+      vscode-languageserver-protocol: 3.17.5
+
+  vscode-uri@3.0.8: {}
+
   w3c-xmlserializer@5.0.0:
     dependencies:
       xml-name-validator: 5.0.0

From 63266a6fc6c5b795289a9b3f7c6266eef7ce2b23 Mon Sep 17 00:00:00 2001
From: Jason Hankins <jason.hankins27@gmail.com>
Date: Wed, 17 Dec 2025 12:56:38 -0500
Subject: [PATCH 06/10] reformat ADRs based on feedback (consistent sections,
 mermaid diagrams, etc.)

---
 ...024-usefragment-vs-httpbatch-dataloader.md | 248 +++++--------
 .../decisions/0025-public-graphql-caching.md  | 257 +++++---------
 .../0026-permission-aware-caching.md          | 326 +++++-------------
 .../decisions/0027-client-side-caching.md     | 146 ++------
 4 files changed, 288 insertions(+), 689 deletions(-)

diff --git a/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md b/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
index 96f900178..b5feb7cf4 100644
--- a/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
+++ b/apps/docs/docs/decisions/0024-usefragment-vs-httpbatch-dataloader.md
@@ -14,25 +14,99 @@ informed:
 
 ## Context and Problem Statement
 
-ShareThrift's GraphQL API serves user profiles, event listings, community feeds, and real-time notifications. As the platform scales, we need clear guidance on when to apply Apollo Client and server-side optimization patterns:
+ShareThrift's GraphQL API serves a variety of different component data. As the platform scales, we need clear guidance on when to apply Apollo Client and server-side optimization patterns:
 - **useFragment** - Creating lightweight cache bindings to eliminate unnecessary re-renders
 - **HTTP Batching** - Reducing network overhead by combining multiple operations
 - **DataLoader** - Solving N+1 database queries for MongoDB aggregations
 
 These patterns optimize different layers and work together to improve performance at scale.
 
-## DataLoader - Database Query Batching
+## Decision Drivers
 
-DataLoader solves the N+1 query problem by batching and caching database requests within a single GraphQL operation.
+- **Performance**: Minimize network requests, database queries, and component re-renders
+- **Developer Experience**: Maintainable, testable, self-documenting code
+- **Scalability**: Patterns must work at production scale
+- **Industry Standards**: Align with Apollo GraphQL and community best practices
+- **Measurability**: Decisions based on benchmarks and real-world testing
+
+## Considered Options
+
+### Option 1: Use All Three Patterns (Comprehensive Optimization)
+Implement useFragment, HTTP batching, and DataLoader together for complete stack optimization.
 
-**Impact for ShareThrift:**
+**DataLoader (Server-Side):**
+- Solves N+1 query problem by batching database requests within a single GraphQL operation
 - Event feed with 50 items + creator profiles: 51 MongoDB queries → 2 queries
 - User search with 20 results + membership data: 21 queries → 2 queries
-- Community page with 100 members + user profiles: 101 queries → 2 queries
+- Automatically batches relationship traversals (10 events with creators: 11 queries → 2 queries)
 
-Without DataLoader, each relationship traversal triggers a separate database query. With 10 events each having a creator, you'd execute 1 query for events + 10 queries for creators = 11 total. DataLoader automatically batches those 10 creator queries into 1.
+**HTTP Batching (Client-Side Network):**
+- Combines multiple GraphQL operations into single HTTP request
+- Dashboard loading (profile + notifications + events): 3 HTTP requests → 1 batched request
+- Waits 20ms to collect operations, eliminating redundant connection setup and SSL handshakes
+- Particularly valuable for HTTP/1.1 connections and high-latency mobile networks
 
-**Query Batching Flow:**
+**useFragment + @nonreactive (Client-Side Re-Renders):**
+- Enables surgical cache updates that eliminate unnecessary re-renders in list rendering
+- Event feed with 50 items: Update one event = 1 re-render instead of 51
+- Components receive IDs only and read directly from cache via independent subscriptions
+- Measured results: 91-99% re-render reduction for list components
+
+### Option 2: Server-Side Only (DataLoader Only)
+Focus on server optimization (DataLoader) without client-side patterns (useFragment, HTTP batching).
+- Eliminates N+1 database queries but doesn't optimize network or client rendering
+- Multiple component queries still trigger separate HTTP requests
+- List updates still cause parent + all children to re-render
+
+### Option 3: Client-Side Only (useFragment + HTTP Batching)
+Optimize client without server-side batching (no DataLoader).
+- Reduces network overhead and re-renders but doesn't solve N+1 database problem
+- Server still executes excessive database queries for relationship traversals
+- Database becomes performance bottleneck under load
+
+### Option 4: Minimal (No Special Optimizations)
+Use basic Apollo Client/Server without optimization patterns.
+- Simplest implementation with no learning curve
+- Suffers from N+1 queries, excessive HTTP requests, and re-render cascades
+- Not viable for production scale with list-heavy UIs
+
+## Decision Outcome
+
+Chosen option: **Use all three patterns** - DataLoader, HTTP Batching, and useFragment + @nonreactive.
+
+DataLoader is non-negotiable for production GraphQL servers as the N+1 problem is universal across MongoDB aggregations and relationship traversals, delivering 95%+ reduction in database queries for relationship-heavy pages. useFragment + @nonreactive provides 91-99% re-render reduction through surgical cache updates where list item updates trigger only 1 re-render instead of parent + all siblings. HTTP Batching consolidates multiple component queries into single requests for dashboard-style UIs where multiple components independently fetch data, reducing 3-4 HTTP requests to a single batched request and eliminating redundant connection overhead - particularly valuable for ShareThrift's mobile users on high-latency networks where Cloudflare research shows 35-50% improvement in multi-query scenarios.
+
+## Technical Considerations
+
+- DataLoader batching occurs within a single GraphQL operation execution tick, collecting all load calls before issuing a single database query with an IN clause
+- HTTP Batching waits 20ms to collect operations from multiple components before sending a single POST request with an array of operations
+- useFragment creates direct cache subscriptions that bypass parent component re-renders, enabling list items to update independently. Unlike useState + useEffect patterns that require manual dependency tracking and effect callbacks, useFragment establishes an automatic reactive subscription to the Apollo Cache - when the cached entity changes, the component automatically re-renders with updated data without any explicit effect setup. The `complete` flag indicates whether all requested fragment fields are available in cache, and the subscription persists for the component's lifetime, similar to how a computed value automatically updates when its dependencies change
+- Fragment colocation allows components to declare their own data requirements, making them portable and preventing breaking changes when moving components
+- ShareThrift uses POST requests for authenticated endpoints (compatible with HTTP Batching) and reserves GET requests with APQ for public CDN-cached endpoints
+- BatchHttpLink configured with batchMax of 10 operations and batchInterval of 20ms balances latency with batching efficiency
+- DataLoaders must be instantiated per-request in GraphQL context to prevent cross-request data leakage between users
+
+### Automatic Persisted Queries (APQ) Compatibility
+
+APQ sends query hashes instead of full query strings to reduce request size. DataLoader, HTTP Batching (POST), useFragment are compatible with APQ. However, HTTP Batching (GET) is not compatible.Must choose between HTTP Batching (POST) OR CDN Caching (GET) - cannot use both simultaneously. **GET mode** (`useGETForHashedQueries: true`)
+
+### Fragment Colocation vs Container Pattern
+
+Fragment colocation places data requirements directly in components alongside their rendering logic, enabling components to declare their own data needs and remain portable across the application. This contrasts with the container pattern where parent components fetch all data and pass it down as props, creating tight coupling and fragile dependencies. Components using fragment colocation can be moved, reused in component libraries, or modified without breaking parent queries - particularly valuable for large development teams (5+ developers) working on list-heavy UIs and complex nested component hierarchies where passing IDs instead of full data objects reduces coupling and prevents breaking changes.
+
+## Consequences
+
+- Good: database queries reduced by 95%+ for relationship-heavy pages
+- Good: network request consolidation improves mobile user experience
+- Good: re-render optimization prevents performance degradation on large lists
+- Good: fragment colocation makes components portable and self-documenting
+- Bad: team must learn cache normalization and fragment composition
+- Bad: DataLoaders must be recreated per-request for security
+- Bad: HTTP batching adds 20ms collection delay
+
+## Implementation Details
+
+### DataLoader Query Batching Flow
 
 ```mermaid
 sequenceDiagram
@@ -50,18 +124,7 @@ sequenceDiagram
     DataLoader-->>Resolver: Distribute cached results to each caller
 ```
 
-## HTTP Batching - Network Request Consolidation
-
-HTTP Batching combines multiple GraphQL operations into a single HTTP request, reducing network overhead.
-
-**Impact for ShareThrift:**
-- Dashboard loading (user profile + notifications + events): 3 HTTP requests → 1 batched request
-- Event detail page (event + comments + creator + attendees): 4 requests → 1 request
-- Particularly valuable for mobile users on high-latency networks
-
-When multiple React components independently fetch data, each triggers a separate HTTP request. HTTP Batching waits 20ms to collect operations and sends them together, eliminating redundant connection setup, headers, and SSL handshakes.
-
-**HTTP Batching Flow:**
+### HTTP Batching Request Consolidation Flow
 
 ```mermaid
 sequenceDiagram
@@ -80,24 +143,7 @@ sequenceDiagram
     Apollo-->>Component2: EventsData
 ```
 
-## useFragment + @nonreactive - Re-Render Optimization
-
-This pattern enables surgical cache updates and eliminates unnecessary re-renders, particularly valuable for list rendering.
-
-**Impact for ShareThrift:**
-- Event feed with 50 items: Updates to one event (like count, attendance) don't re-render the entire feed
-- Community member list with 100 users: Profile updates only re-render affected member cards
-- Notification list: New notifications don't trigger re-renders of existing items
-
-**Key Benefits:**
-- Pass only cache keys (IDs) as props instead of full data objects
-- Components read directly from cache without parent re-renders
-- Each list item subscribes only to its own cache data
-- Updates to one item don't cascade to siblings or parents
-
-This isn't a speed optimization - it's a re-render reduction pattern that prevents performance degradation at scale.
-
-**Re-Render Optimization Flow:**
+### useFragment Re-Render Optimization Flow
 
 ```mermaid
 graph TB
@@ -118,150 +164,32 @@ graph TB
         Cache2[Apollo Cache] -.->|direct subscription| Child2B
         Note2[Update Child 2 data<br/>Result: Only Child 2 re-renders]
     end
+```
 
-
-## Decision Drivers
-
-- **Performance**: Minimize network requests, database queries, and component re-renders
-- **Developer Experience**: Maintainable, testable, self-documenting code
-- **Scalability**: Patterns must work at production scale
-- **Industry Standards**: Align with Apollo GraphQL and community best practices
-- **Measurability**: Decisions based on benchmarks and real-world testing
-
-## Considered Options
-
-### Option 1: Use All Three Patterns (Comprehensive Optimization)
-Implement useFragment, HTTP batching, and DataLoader together for complete stack optimization.
-
-### Option 2: Server-Side Only (DataLoader Only)
-Focus on server optimization (DataLoader) without client-side patterns (useFragment, HTTP batching).
-
-### Option 3: Client-Side Only (useFragment + HTTP Batching)
-Optimize client without server-side batching (no DataLoader).
-
-### Option 4: Minimal (No Special Optimizations)
-Use basic Apollo Client/Server without optimization patterns.
-
-## Decision Outcome
-
-Chosen option: **Use all three patterns** - DataLoader, HTTP Batching, and useFragment + @nonreactive.
-
-### Rationale
-
-**DataLoader** is non-negotiable for production GraphQL servers. The N+1 problem is universal across MongoDB aggregations and relationship traversals.
-
-**useFragment + @nonreactive** provides specific benefits for ShareThrift's list-heavy UI:
-   
-   **Primary Benefits** (Re-Render Reduction):
-   - **Surgical cache updates**: Update one item = only that component re-renders (91-99% re-render reduction)
-   - **@nonreactive pattern**: Parent watches IDs only, ignoring data field changes
-   - **Direct cache subscriptions**: Each child subscribes to its own cache entry independently
-   - **List rendering power**: 100-item list, update 1 item = 1 re-render instead of 101
-   - **Measured results**: FragmentDemo shows 11 re-renders → 1 re-render (10-item list)
-   
-   **Fragment Colocation Benefits** (Code Organization):
-   - Components declare their own data needs, preventing breaking changes
-   - Self-contained, portable components
-   - Pass lightweight IDs instead of full data objects
-   - Reduces coupling between parent and child components
-   - Especially valuable for:
-     - List components with many items
-     - Reusable component libraries
-     - Large development teams (5+ developers)
-     - Complex nested component hierarchies
-   
-   **Important Limitations:**
-   - `useFragment` creates cache subscriptions that **bypass React.memo optimization**
-   - Not primarily about performance - initial render speed is similar to props
-   - Most benefit comes from **avoiding re-render waterfalls**, not faster execution
-   - Consider `useBackgroundQuery` for actual perceived performance improvements
-
-**HTTP Batching** is valuable for ShareThrift's dashboard and multi-component pages:
-   - HTTP/1.1 connections (majority of mobile traffic)
-   - High-latency networks
-   - Dashboard-style UIs with 10+ independent queries executing simultaneously
-   - **Research**: Cloudflare study shows 35-50% improvement in multi-query scenarios
-
-   **Important Limitation:**
-   - HTTP Batching does not provide improvement on static web pages or sites with minimal queries.
-   - Large batchIntervals and small batchIntervals will have linear effects on the performance depending on the number of simultaneous requests. (If you have a large batch and a small number of requests, you may end up waiting longer than necessary)
-
-### Implementation for ShareThrift
-
-**DataLoader (Server):**
-- Configure loaders for User, Event, and Community entities
-- Initialize per-request to maintain security boundaries
-- Batch database queries within single operation execution
-
-**HTTP Batching (Client):**
-- Configure BatchHttpLink with 20ms collection window
-- Set maximum batch size of 10 operations
-- Apply to authenticated GraphQL endpoint
-
-**Fragment Colocation (Client):**
-- Define fragments alongside components that use them
-- Compose fragments into parent queries
-- Enables component portability and self-documentation
-
-**useFragment + @nonreactive Pattern (Client):**
-- Parent queries fetch IDs and mark fragments as @nonreactive
-- Parent re-renders only when list composition changes (items added/removed)
-- Child components use useFragment to read directly from cache
-- Cache updates trigger re-renders only in affected children
-
-### Consequences
-
-- Good, because database queries reduced by 95%+ for relationship-heavy pages
-- Good, because network request consolidation improves mobile user experience
-- Good, because re-render optimization prevents performance degradation on large lists
-- Good, because fragment colocation makes components portable and self-documenting
-- Bad, because team must learn cache normalization and fragment composition
-- Bad, because DataLoaders must be recreated per-request for security
-- Bad, because HTTP batching adds 20ms collection delay
-
-## Validation
-
-### Performance Testing (Completed)
+## Validation with Performance Testing
 
 Created test pages to validate each pattern:
 
 1. **HTTP Batching Test** ([BatchingDemo.tsx](https://github.com/jason-t-hankins/Social-Feed/blob/main/client/src/demos/01-http-batching/BatchingDemo.tsx))
    - Compares batched vs non-batched requests
    - Measures total request time and HTTP request count
-   - **Result**: 3-5 simultaneous queries show 40% improvement with batching
+   - **Result**: 3-5 simultaneous queries show 40% performance improvement with batching
 
 2. **useFragment Test** ([FragmentDemo.tsx](https://github.com/jason-t-hankins/Social-Feed/blob/main/client/src/demos/02-usefragment/FragmentDemo.tsx))
-   - Side-by-side comparison: WITHOUT vs WITH useFragment + @nonreactive
    - 10-item list with like buttons on each post
    - **WITHOUT**: Clicking any button = 11 re-renders (parent + 10 children)
    - **WITH**: Clicking any button = 1 re-render (only clicked post)
    - **Result**: 91% re-render reduction, scaling to 99% with larger lists
-   - **Key Finding**: useFragment + @nonreactive is NOT about speed - it's about eliminating unnecessary re-renders through surgical cache updates and direct component-to-cache subscriptions
 
-3. **DataLoader Test** (Present in all tests)
+3. **DataLoader Test** ([ApproachComparison.tsx](https://github.com/jason-t-hankins/Social-Feed/blob/main/client/src/demos/06-full-comparison/ApproachComparison.tsx))
    - Visualizes N+1 query resolution
    - Shows server-side batching logs
    - **Result**: 10 posts + authors = 2 queries (vs 11 without DataLoader)
 
-
-
 ## More Information
 
 - [Social-Feed Demo Application](https://github.com/jason-t-hankins/Social-Feed/)
 - [Apollo GraphQL Documentation](https://www.apollographql.com/docs/)
 - [DataLoader GitHub Repository](https://github.com/graphql/dataloader)
 - [Shopify Engineering: Solving N+1 Problem](https://shopify.engineering/solving-the-n-1-problem-for-graphql-through-batching)
-- [Apollo Client useFragment Discussion](https://github.com/apollographql/apollo-client/issues/11118)
-
-### Automatic Persisted Queries (APQ) Compatibility
-
-APQ sends query hashes instead of full query strings to reduce request size.
-
-**Compatibility:** DataLoader, HTTP Batching (POST), useFragment. However, HTTP Batching (GET) is not compatible.
-
-**Key Trade-off:** Choose between HTTP Batching (POST) OR CDN Caching (GET) - cannot use both simultaneously.
-
-- **ShareThrift uses POST** (default) - fully APQ-compatible
-- **GET mode** (`useGETForHashedQueries: true`) enables CDN caching but disables batching
-- **Production choice:** Dashboard/admin = batching (POST), Public content = CDN (GET)
-
+- [Apollo Client useFragment Discussion](https://github.com/apollographql/apollo-client/issues/11118)
\ No newline at end of file
diff --git a/apps/docs/docs/decisions/0025-public-graphql-caching.md b/apps/docs/docs/decisions/0025-public-graphql-caching.md
index 7e6c3905c..dabff13db 100644
--- a/apps/docs/docs/decisions/0025-public-graphql-caching.md
+++ b/apps/docs/docs/decisions/0025-public-graphql-caching.md
@@ -35,49 +35,102 @@ We need guidance for enabling public caching of unauthenticated queries while ma
 
 ### Option 1: Separate Endpoints (Public + Authenticated)
 
-Create two distinct GraphQL endpoints:
-- `/graphql` - Authenticated, requires JWT, POST requests
-- `/graphql-public` - No auth, GET requests with APQ
+Create two distinct GraphQL endpoints with physical separation:
+- `/graphql` - Authenticated endpoint with POST requests, JWT tokens, HTTP batching, private cache headers
+- `/graphql-public` - Public endpoint with GET requests, APQ, CDN-friendly cache headers (5min browser, 1hr CDN)
+
+**Benefits:**
+- Physical endpoint separation eliminates token leakage risk
+- Public endpoint optimized for CDN caching with GET + APQ (80-95% cache hit rate, 97% faster responses)
+- Authenticated endpoint optimized for HTTP batching and DataLoader
+- Clear audit trail and impossible to accidentally cache authenticated requests
+
+**Trade-offs:**
+- Two Apollo Client instances to maintain
+- Must categorize queries as public vs private
+- GET requests cannot be batched (choose batching OR caching)
 
 ### Option 2: Same Endpoint with Conditional Auth
 
-Use a single endpoint with conditional authentication based on query/operation.
+Use single `/graphql` endpoint with conditional authentication based on operation name:
+- Client maintains whitelist of operations requiring authentication
+- Context link checks operation name before adding auth header
+- Public queries send custom header to signal caching eligibility
+- Server dynamically sets cache policy based on header
+
+**Benefits:**
+- Single Apollo Client instance
+- Single endpoint to manage
+- No query duplication
+
+**Trade-offs:**
+- Security risk: Misconfigured whitelist could expose tokens to CDN
+- Maintenance burden: Must keep operation whitelist synchronized
+- Audit complexity: Harder to track which queries are public
+- Testing overhead: More edge cases to validate
 
 ### Option 3: No Public Caching
 
-Continue with current approach - all queries authenticated, no public caching.
+Continue with current approach - all queries authenticated, no public caching:
+- Single endpoint, all requests require JWT
+- POST requests only
+- Server handles 100% of traffic
+
+**Benefits:**
+- Simplest implementation
+- No security concerns about public caching
+
+**Trade-offs:**
+- Server handles all public traffic without CDN offloading
+- Higher infrastructure costs
+- Slower response times for public content
+- No bandwidth savings from APQ
 
 ## Decision Outcome
 
-Chosen option: **Separate endpoints** - `/graphql` for authenticated requests and `/graphql-public` for public requests.
+Recommended option: **Separate endpoints** - `/graphql` for authenticated requests and `/graphql-public` for public requests.
 
-**Security**: Physical separation eliminates token leakage risk. Public endpoint never sees Authorization headers.
+Physical endpoint separation eliminates token leakage risk as the public endpoint never sees Authorization headers, making it impossible to accidentally cache authenticated data. Each endpoint is optimized for its use case - the public endpoint uses GET requests with APQ and CDN-friendly cache headers (5min browser, 1hr CDN) delivering 80-95% cache hit rates and 97% faster response times (5ms vs 200ms), while the authenticated endpoint uses POST requests with HTTP batching and DataLoader for optimal query consolidation. Standard HTTP caching works with any CDN (Cloudflare, Fastly, Akamai) without custom configuration, and clear boundaries make public queries easy to audit and validate.
 
-**Performance**: Each endpoint optimized for its use case - public uses GET requests with APQ and HTTP caching, authenticated uses POST with HTTP batching and DataLoader.
+## Technical Considerations
 
-**Compatibility**: Standard HTTP caching works with any CDN without custom configuration.
+- Single Apollo Server instance serves both endpoints with different cache policies based on context
+- Public endpoint disables CSRF prevention to allow GET requests and requires additional safeguards: rate limiting, request validation, header checks
+- GET request query parameters transformed to request body for Apollo Server compatibility before processing
+- Cache-Control headers set dynamically: public endpoint uses `public, max-age=300, s-maxage=3600`, authenticated endpoint uses `private, no-cache, no-store, must-revalidate`
+- Public schema explicitly defines queries with `public` prefix for clear auditing and returns sanitized types without sensitive fields
+- CDN serves 80-95% of public requests with edge caching reducing latency for geographically distributed users
+- Must carefully categorize queries as public or private with clear naming conventions and schema boundaries
 
-**Maintainability**: Clear boundaries make public queries easy to audit and validate.
+### Automatic Persisted Queries (APQ)
 
-## Implementation Details
+APQ sends SHA-256 hash of query instead of full query string (64 chars vs 100s-1000s chars), enabling GET requests that CDNs can cache by URL. Client configures persisted query link with SHA-256 hashing and enables GET requests for hashed queries via `useGETForHashedQueries`. Apollo Server supports APQ out-of-the-box with no additional configuration required. APQ reduces bandwidth by 90% for typical queries, particularly valuable for mobile users.
 
-### Server Architecture
+### ShareThrift Query Classification Example
+
+| Query | Public? | Reason |
+|-------|---------|--------|
+| `userById()` |  Yes | Should be able to see users' pages, specifics may be blocked |
+| `accountPlans()` |  Yes | Shown to unauthenticated users during signup |
+| `currentUser()` |  No | requires authentication and could cause errors |
+| `adminUserById()` |  No | specific calls like this could leak sensitive info |
 
-**Dual Endpoint Configuration:**
-- Single Apollo Server instance serves both endpoints
-- `/graphql` - Authenticated endpoint with POST requests and private cache headers
-- `/graphql-public` - Public endpoint with GET requests and CDN-friendly cache headers
+## Consequences
 
-**Cache Control Strategy:**
-- Public endpoint: `Cache-Control: public, max-age=300, s-maxage=3600` (5min browser, 1hr CDN)
-- Authenticated endpoint: `Cache-Control: private, no-cache, no-store, must-revalidate`
+- Good: CDN serves 80-95% of public requests reducing server load and infrastructure costs
+- Good: 97% faster response times for cached content (5ms vs 200ms)
+- Good: physical endpoint separation eliminates token leakage risk with clear audit trail
+- Good: works with any CDN (Cloudflare, Fastly, Akamai) with standard HTTP caching
+- Good: APQ reduces bandwidth by 90% for typical queries, particularly valuable for mobile users
+- Bad: two Apollo Client instances to maintain with separate schema subsets
+- Bad: must carefully categorize queries as public or private
+- Bad: stale data risk with long TTLs requires purge strategy for urgent updates
+- Bad: GET requests cannot be batched (trade-off: choose batching OR caching, not both)
+- Bad: team must understand two different patterns with testing for both endpoints
 
-**Security Considerations:**
-- Public endpoint disables CSRF prevention to allow GET requests
-- Must implement additional safeguards: rate limiting, request validation, header checks
-- GET request query parameters transformed to request body for Apollo Server compatibility
+## Implementation Details
 
-**Request Flow:**
+### Public and Authenticated Endpoint Request Flow
 
 ```mermaid
 sequenceDiagram
@@ -101,159 +154,15 @@ sequenceDiagram
     Note over CDN: Not cached by CDN
 ```
 
-### Client Configuration
-
-**Authenticated Client:**
-- Targets `/graphql` endpoint
-- Adds JWT token from localStorage to Authorization header
-- Uses POST requests for all operations
-- Compatible with HTTP batching
-
-**Public Client:**
-- Targets `/graphql-public` endpoint
-- Configures Automatic Persisted Queries (APQ) with SHA-256 hashing
-- Enables GET requests for hashed queries via `useGETForHashedQueries`
-- No authorization headers sent
-- Leverages CDN and network provider caching
-
-### Schema Design
-
-**Public Schema Subset:**
-- Explicitly defined queries for unauthenticated access
-- Examples: `publicFeed`, `publicPost`, `publicUser`
-- Returns sanitized types without sensitive fields
-- Clearly prefixed with `public` for auditing
-
-**Authenticated Schema:**
-- Full query set including user-specific operations
-- Includes personalized queries: `myFeed`, `myProfile`
-- Returns complete types with all fields
-- Requires valid JWT token
-
-### Cache-Control Headers
-
-**Public Endpoint Strategy:**
-- `max-age=300`: Browser caches for 5 minutes
-- `s-maxage=3600`: CDN/shared caches for 1 hour
-- `public`: Explicitly allows intermediate caching
-
-**Authenticated Endpoint Strategy:**
-- `private`: Only browser may cache (not CDN)
-- `no-cache`: Must revalidate before using cached copy
-- `no-store`: Prevent any caching mechanism from storing data
-- `must-revalidate`: Strict cache validation required
-
-## Automatic Persisted Queries (APQ)
-
-### What is APQ?
-
-APQ sends a SHA-256 hash of the query instead of the full query string:
-
-```
-# Without APQ (POST)
-POST /graphql-public
-{
-  "query": "query GetFeed { feed { edges { node { id content } } } }"
-}
-
-# With APQ (GET)
-GET /graphql-public?extensions={"persistedQuery":{"version":1,"sha256Hash":"abc123..."}}
-```
-
-### Benefits
-
-1. **Reduced request size**: Hash (64 chars) vs full query (100s-1000s chars)
-2. **Cacheable GET requests**: CDNs cache by URL
-3. **Bandwidth savings**: Especially for mobile users
-
-### Implementation
-
-**Client-Side:**
-- Import persisted query link from Apollo Client
-- Configure SHA-256 hashing function
-- Enable GET requests for hashed queries
-- Chain with HTTP link
-
-**Server-Side:**
-- Apollo Server supports APQ out-of-the-box (enabled by default)
-- No additional configuration required
-
-## Consequences
-
-### Good
-
-1. **Reduced Server Load**
-   - CDN serves 80-95% of public requests
-   - Server handles only cache misses and authenticated requests
-   - Scales to handle traffic spikes without infrastructure changes
-
-2. **Improved Performance**
-   - 97% faster response times for cached content (5ms vs 200ms)
-   - Edge caching reduces latency for geographically distributed users
-   - APQ reduces bandwidth by 90% for typical queries
-
-3. **Security Benefits**
-   - Physical endpoint separation eliminates token leakage risk
-   - Clear audit trail for public vs private access
-   - Impossible to accidentally cache authenticated requests
-
-4. **Standard HTTP Compliance**
-   - Works with any CDN (Cloudflare, Fastly, Akamai)
-   - Compatible with ISP caching infrastructure
-   - No vendor lock-in or custom configuration required
-
-### Bad
-
-1. **Increased Complexity**
-   - Two Apollo Client instances to maintain
-   - Separate schema subsets for public vs private queries
-   - Must carefully categorize queries as public or private
-
-2. **Cache Invalidation Challenges**
-   - Stale data risk with long TTLs
-   - Need purge strategy for urgent updates
-   - CDN cache may lag behind database changes
-
-3. **Loss of HTTP Batching**
-   - GET requests cannot be batched
-   - Multiple public queries = multiple HTTP requests
-   - Trade-off: choose batching OR caching, not both
-
-4. **Developer Overhead**
-   - Team must understand two different patterns
-   - Risk of confusion about which client to use
-   - Testing requires validating both endpoints
+## Validation with Performance Testing
 
-## ShareThrift Query Classification
-
-| Query | Public? | Reason |
-|-------|---------|--------|
-| `userById()` |  Yes | Should be able to see users' pages, specifics may be blocked |
-| `accountPlans()` |  Yes | Shown to unauthenticated users during signup |
-| `currentUser()` |  No | requires authentication and could cause errors |
-| `adminUserById()` |  No | specific calls like this could leak sensitive info |
-
-
-
-### Alternative Approach: Same Endpoint with Conditional Auth
-
-This approach uses a single `/graphql` endpoint for both authenticated and public queries, with conditional logic to determine when to include authentication headers.
-
-**How It Works:**
-1. Client maintains whitelist of operations requiring authentication
-2. Context link checks operation name before adding auth header
-3. Public queries send custom header to signal caching eligibility
-4. Server reads header and sets cache policy dynamically
-5. Single Apollo Server instance handles both request types
-
-**Drawbacks:**
-- Security risk: Misconfigured whitelist could expose tokens to CDN
-- Maintenance burden: Must keep operation whitelist synchronized
-- Audit complexity: Harder to track which queries are public
-- Testing overhead: More edge cases to validate
+Created test pages to validate each pattern:
 
-**Not Recommended** - Separate endpoints provide clearer security boundaries
+1. **Public Caching Test** ([PublicCachingDemo.tsx](https://github.com/jason-t-hankins/Social-Feed/blob/main/client/src/demos/03-public-caching/PublicCachingDemo.tsx))
+   - Demonstrates the differences between authenticated and public GraphQL queries for enabling CDN/ISP caching.
 
+2. **Public Caching Test** ([ConditionalAuthDemo.tsx](https://github.com/jason-t-hankins/Social-Feed/blob/main/client/src/demos/03-public-caching/ConditionalAuthDemo.tsx))
+   - Demonstrates using a single endpoint with conditional auth for public caching
 
 ## More Information
 
diff --git a/apps/docs/docs/decisions/0026-permission-aware-caching.md b/apps/docs/docs/decisions/0026-permission-aware-caching.md
index 140585ce7..75fa35c20 100644
--- a/apps/docs/docs/decisions/0026-permission-aware-caching.md
+++ b/apps/docs/docs/decisions/0026-permission-aware-caching.md
@@ -14,9 +14,7 @@ informed:
 
 ## Context and Problem Statement
 
-ShareThrift's GraphQL API serves data to users with different permission levels - regular members, community admins, and platform administrators. A naive server-side caching implementation could accidentally serve admin-only data to regular users, creating serious security vulnerabilities.
-
-For example, admin users viewing event analytics (attendance rates, revenue) and regular members viewing the same event listing must not share cached data. Without permission-aware caching, an admin's cached response could leak sensitive information to regular users.
+ShareThrift's GraphQL API serves data to users with different permission levels - personal users, and admin users. A naive server-side caching implementation could accidentally serve admin-only data to regular users through the cache response, creating serious security vulnerabilities.
 
 ## Decision Drivers
 
@@ -30,49 +28,108 @@ For example, admin users viewing event analytics (attendance rates, revenue) and
 
 ### Option 1: No Server-Side Caching
 
-Don't cache at the GraphQL layer - compute fresh for every request.
+Compute fresh data for every GraphQL request without any caching layer.
+
+**Benefits:**
+- Zero risk of serving stale or incorrect data
+- No permission leakage concerns
+- Simplest implementation with no cache management overhead
+
+**Trade-offs:**
+- Database executes same queries repeatedly for identical requests
+- 50-200ms database query latency on every request
+- Server load increases linearly with request volume
+- Not viable for production scale with high traffic
 
 ### Option 2: Permission-Aware Cache Keys
 
-Include user permissions in cache keys to ensure isolation between permission levels.
+Include user permissions (userId, role, permissions array) in cache keys to ensure isolation between permission levels.
+
+**Benefits:**
+- Users with identical permissions share cache entries (1000 members = 1 cache entry)
+- 70-90% reduction in database queries for same permission sets
+- Cache lookups under 1ms vs 50-200ms database queries
+- Supports complex permission models (RBAC, ABAC, custom)
+- Zero risk of permission leakage between users
+
+**Trade-offs:**
+- One cache entry per unique permission set increases memory usage
+- Changing user permissions requires invalidating their cache entries
+- First request for each permission level suffers cold cache penalty
+- Team must understand cache key composition and invalidation strategies
 
 ### Option 3: Post-Fetch Filtering
 
-Cache the full dataset, then filter based on permissions before returning.
+Cache full dataset without permission context, then filter based on user permissions before returning.
+
+**Benefits:**
+- Single cache entry serves all users regardless of permissions
+- Minimal memory usage
+- Simple cache key structure
+
+**Trade-offs:**
+- Security risk: Full data including sensitive fields stored in cache
+- Performance penalty: Must filter on every request negating cache benefits
+- Cache inspector or debugging could expose unauthorized data
+- Violates defense-in-depth security principle
 
 ### Option 4: Separate Queries Per Permission Level
 
-Create distinct queries for each permission level (e.g., `adminFeed`, `userFeed`).
+Create distinct GraphQL queries for each permission level (e.g., `adminFeed`, `userFeed`, `premiumFeed`).
+
+**Benefits:**
+- Clear separation between permission levels
+- Simple caching without permission logic in keys
+- Explicit schema defines what each role can access
+
+**Trade-offs:**
+- Schema duplication for similar queries across permission levels
+- Maintenance burden: Update multiple queries when schema changes
+- Client complexity: Must know which query to call for current user
+- Doesn't scale with fine-grained or dynamic permissions
 
 ## Decision Outcome
 
-Chosen option: **Permission-aware cache keys** - Include user permissions in cache keys to ensure isolation between permission levels.
+Recommended option: **Permission-aware cache keys** - Include user permissions in cache keys to ensure isolation between permission levels.
 
-**Security**: Cache keys include query, variables, userId, role, and permissions. Example: `GetEvents::{"first":5}::alice::admin::[]` vs `GetEvents::{"first":5}::bob::member::[]`. Users cannot access cached data for other permission levels.
+Cache keys include query, variables, userId, role, and permissions array (e.g., `GetEvents::{"first":5}::alice::admin::[]` vs `GetEvents::{"first":5}::bob::member::[]`) ensuring users cannot access cached data for other permission levels while allowing users with identical permissions to share cache entries (1000 regular members = 1 cache entry). GraphQL resolvers perform permission checks before returning fields and store only filtered results in cache, delivering 70-90% reduction in database queries for users with same permissions with cache lookups under 1ms vs 50-200ms database queries. In-memory Map-based storage provides fast lookups with configurable max size (default 1000 entries) and TTL (default 60 seconds), using LRU eviction when max size is reached. ShareThrift implements hybrid invalidation strategy combining 30-60 second TTL with event-based invalidation on mutations for balance between fresh data and cache efficiency, with per-role cache hit/miss logging for monitoring and optimization.
 
-**Efficiency**: Users with identical permissions share cache entries. 1000 regular members = 1 cache entry.
+## Technical Considerations
 
-**Field-Level Control**: GraphQL resolvers check permissions before returning fields, storing only filtered results in cache.
+- Cache keys concatenate query name, JSON-stringified variables, userId, role, and sorted permissions array into unique string (e.g., `GetFeedWithAnalytics::{"first":5}::alice::admin::[]`)
+- Permission check occurs before cache lookup - unauthorized requests return null immediately without caching
+- Resolvers check permissions at field level, storing only filtered results in cache to prevent sensitive data leakage
+- In-memory Map-based storage provides sub-millisecond lookups with automatic cleanup of expired entries
+- LRU eviction strategy enforces max size limit (default 1000 entries) by removing oldest entry when capacity reached
+- TTL-based expiration (default 60 seconds) with per-entry TTL override support balances freshness with cache efficiency
+- Pattern-based invalidation supports wildcard matching on query, userId, or role for targeted cache clearing on mutations
+- Cache key granularity configurable: role-level for shared non-personalized data (all admins share analytics dashboard), user-level for personalized data (each user's feed)
+- Hybrid invalidation strategy combines TTL expiration with event-based mutations for immediate freshness with safety net
+- Works with Apollo Server, Express GraphQL, and existing DataLoader optimizations without conflicts
 
-**Compatibility**: Works with Apollo Server, Express GraphQL, and existing DataLoader optimizations.
+### Cache Invalidation Strategies
 
-## Implementation Details
+**Time-Based (TTL):** Entries expire after configured duration (30-60 seconds recommended). Simple and predictable but may serve stale data for TTL duration.
 
-### Cache Key Structure
+**Event-Based:** Manually invalidate on mutations by updating database then invalidating affected cache queries. Always fresh data but more complex with risk of over-invalidation. Examples include: Role change, data update.
 
-**Components:**
-- **Query**: Operation name (e.g., "GetFeedWithAnalytics")
-- **Variables**: Query parameters (e.g., `{ first: 5 }`)
-- **User ID**: Unique user identifier (e.g., "507f1f77bcf86cd799439011")
-- **Role**: User role (e.g., "admin", "user")
-- **Permissions**: Additional permission flags (e.g., ["read:analytics"])
+**Hybrid (Recommended):** Combine 30-60 second TTL with mutation-based invalidation. Provides fresh data for mutations with TTL safety net for missed invalidations. Limits to cache memory should be set and an algorithm like LRU or FIFO should be used to evict cache entries.
 
-**Generated Key Example:**
-```
-GetFeedWithAnalytics::{"first":5}::alice::admin::[]
-```
+## Consequences
 
-**Cache Isolation:**
+- Good: zero risk of permission leakage between users with cache key isolation
+- Good: 70-90% reduction in database queries for users with same permissions
+- Good: cache lookups under 1ms vs 50-200ms database queries
+- Good: supports complex permission models (RBAC, ABAC, custom)
+- Good: cache hits and misses logged per role for monitoring and optimization
+- Bad: one cache entry per unique permission set increases memory usage
+- Bad: changing user permissions requires invalidating their cache entries
+- Bad: first request for each permission level suffers cold cache penalty
+- Bad: team must understand cache key composition and invalidation strategies
+
+## Implementation Details
+
+### Cache Isolation Diagram
 
 ```mermaid
 graph LR
@@ -95,18 +152,7 @@ graph LR
     B -.isolated from.-> A
 ```
 
-### Permission-Aware Resolver
-
-**Resolution Flow:**
-1. **Permission Check**: Validate user has required role/permissions
-2. **Early Return**: Return null for unauthorized requests (don't cache)
-3. **Cache Key Generation**: Include query, variables, userId, and role
-4. **Cache Lookup**: Check if entry exists for this permission context
-5. **Database Fetch**: On cache miss, fetch from database
-6. **Cache Storage**: Store with TTL (typically 30-60 seconds)
-7. **Return Data**: Provide cached or fresh data to client
-
-**Resolver Flow:**
+### Permission-Aware Resolver Flow
 
 ```mermaid
 sequenceDiagram
@@ -133,210 +179,12 @@ sequenceDiagram
     end
 ```
 
-### Cache Implementation
-
-**Core Features:**
-- In-memory Map-based storage for fast lookups (< 1ms)
-- Configurable max size (default: 1000 entries)
-- Configurable default TTL (default: 60 seconds)
-- LRU (Least Recently Used) eviction when max size reached
-
-**Key Methods:**
-
-**generateKey**: Concatenates query, variables, userId, role, and permissions into unique string
-
-**get**: 
-- Generates cache key from components
-- Checks if entry exists and is not expired
-- Returns data or null (with automatic cleanup of expired entries)
-
-**set**:
-- Enforces max size limit with LRU eviction
-- Stores data with timestamp and TTL
-- Allows per-entry TTL override
-
-**invalidate**:
-- Pattern-based cache clearing
-- Supports wildcard matching on query, userId, or role
-- Returns count of deleted entries for monitoring
-
-
-## Consequences
-
-- Good, because zero risk of permission leakage between users
-- Good, because reduces database queries by 70-90% for users with same permissions
-- Good, because cache lookups under 1ms vs 50-200ms database queries
-- Good, because supports complex permission models (RBAC, ABAC, custom)
-- Good, because cache hits and misses logged per role for monitoring
-- Bad, because one cache entry per unique permission set increases memory usage
-- Bad, because changing user permissions requires invalidating their cache entries
-- Bad, because first request for each permission level is always slow (cold cache)
-
-
-## Trade-Offs
-
-### Memory vs. Performance
-
-**Low TTL (Time to Live) (10-30s):**
-- Fresh data
-- Lower memory usage
-- ...More database queries
-
-**High TTL (5-10min):**
-- Fewer database queries
-- Better performance
-- ...Higher memory usage
-- ...Stale/Outdated data risk
-
-**Recommendation**: 30sec-5min TTL for most use cases (Feed, Dashboard, User Profile, etc.)
-
-### Granularity
-
-**Coarse (role-level):**
-- Cache key includes query, variables, and role only
-- All users with same role share cache entry
-- Best for non-personalized data
-- Example: All admins see same analytics dashboard
-
-**Fine (user-level):**
-- Cache key includes query, variables, userId, and role
-- Each user has isolated cache entry
-- Required for personalized data
-- Example: Each user's personal feed
-
-**Recommendation**: 
-- Use role-level for data that doesn't vary per user
-- Use user-level for personalized data
-- Hybrid approach: include `userId` only when needed
-
-## Cache Invalidation Strategies
-
-### Time-Based (TTL)
-
-Entries automatically expire after configured duration (e.g., 60 seconds).
-
-**Pros:** Simple, predictable
-**Cons:** May serve stale data for TTL duration
-
-### Event-Based
-
-Manually invalidate cache entries when underlying data changes (e.g., on mutations).
-
-**Process:**
-1. Update data in database
-2. Invalidate affected cache queries
-3. Next request fetches fresh data
-
-**Pros:** Always fresh data
-**Cons:** More complex, can invalidate too aggressively
-
-### Hybrid (Recommended)
-
-Combine TTL expiration with event-based invalidation:
-- Set reasonable TTL (30-60 seconds)
-- Invalidate on mutations for immediate freshness
-- TTL serves as safety net for missed invalidations
-
-**Balance:** Fresh data for mutations, caching for reads
-
-## Real-World Scenarios
-
-### Scenario 1: Role Change
-
-**Problem:** Alice is promoted from `user` to `admin`
-
-**Solution:**
-1. Update user role in database
-2. Invalidate all cache entries matching userId
-3. Next request generates fresh cache with new role
-4. User immediately sees admin-only data
-
-### Scenario 2: Data Update
-
-**Problem:** Admin updates a post, all users should see new content
-
-**Solution:**
-1. Update post in database
-2. Invalidate all cache entries for affected queries (GetFeed, GetPost)
-3. Clear cache across all user roles
-4. Next request for any user fetches fresh data
-
-### Scenario 3: Permission Check Change
-
-**Problem:** Analytics permission logic changes (now requires `premium` flag)
-
-**Solution:**
-1. Update resolver permission check to require admin OR premium
-2. Modify cache key generation to include premium flag in permissions array
-3. During deployment, invalidate all PostAnalytics cache entries
-4. New cache entries generated with updated permission model
-5. Admin and premium users both see analytics (in separate cache entries)
-
-## Edge Cases & Mitigations
-
-### Edge Case: Permission Check in Middle of Resolver Chain
-
-**Problem:**
-Root query fetches all posts without permission check, but nested field `analytics` requires admin role. If we cache at root query level, admin and user caches would be identical.
-
-**Solution:**
-Cache at the field level where permission check occurs:
-1. Root query (posts) caches without permission context
-2. Nested field (analytics) caches with role in key
-3. Admin gets cached analytics, user gets null
-4. Two separate cache entries maintain security boundary
-
-### Edge Case: Dynamic Permissions
-
-**Problem:** User has permission `["posts:read:own"]` - can only read their own posts
-
-**Solution:**
-1. Include userId in cache key (not just role)
-2. Include full permissions array in cache key
-3. Each user gets isolated cache entry
-4. No risk of cross-user data leakage
-
-### Edge Case: Memory Leak from User Churn
-
-**Problem:** 10,000 users log in once, cache grows unbounded
-
-**Solution:**
-1. Enforce maximum cache size limit (e.g., 1000 entries)
-2. Implement LRU (Least Recently Used) eviction strategy
-3. When max size reached, remove oldest entry before adding new one
-4. Protects against memory exhaustion from one-time users
-
-## Monitoring & Observability
-
-### Key Metrics
-
-```typescript
-interface CacheMetrics {
-  totalSize: number;          // Current cache entry count
-  hitRate: number;           // Percentage of cache hits
-  hitsByRole: Map<string, number>;  // Cache hits per role
-  missedByRole: Map<string, number>; // Cache misses per role
-  avgTTL: number;            // Average entry age
-  evictionCount: number;     // Times max size was hit
-}
-```
-
-### Logging
+## Validation with Performance Testing
 
-```typescript
-cache.get(key) {
-  if (cached) {
-    console.log(`[Cache HIT] ${key.query} for role=${key.role}`);
-  } else {
-    console.log(`[Cache MISS] ${key.query} for role=${key.role}`);
-  }
-}
-
-cache.invalidate(pattern) {
-  console.log(`[Cache INVALIDATE] ${deletedCount} entries`, pattern);
-}
-```
+Created a single test page to validate caching
 
+1. **Public Caching Test** ([PermissionCacheDemo.tsx](https://github.com/jason-t-hankins/Social-Feed/blob/main/client/src/demos/04-permission-cache/PermissionCacheDemo.tsx))
+   - Demonstrates server-side in-memory caching that respects user permissions.
 
 ## More Information
 
diff --git a/apps/docs/docs/decisions/0027-client-side-caching.md b/apps/docs/docs/decisions/0027-client-side-caching.md
index 9a2cf5a45..e1c9310bd 100644
--- a/apps/docs/docs/decisions/0027-client-side-caching.md
+++ b/apps/docs/docs/decisions/0027-client-side-caching.md
@@ -19,7 +19,6 @@ ShareThrift requires responsive UI and reduced server load through effective cli
 - Cache policy selection (cache-first, network-only, cache-and-network)
 - Security considerations for preventing sensitive data exposure in client cache
 - Cache invalidation strategies for mutations
-- Effective use of Apollo DevTools for debugging
 
 This decision focuses on cache policy patterns with emphasis on security and data freshness requirements.
 
@@ -31,56 +30,23 @@ This decision focuses on cache policy patterns with emphasis on security and dat
 - Data Freshness: Balance caching with real-time requirements
 - Developer Experience: Clear patterns that scale with team size
 
-## Considered Options
-
-### Apollo Client vs Alternatives
-
-Evaluated: Apollo Client, TanStack Query, SWR, Redux RTK Query
-
-**Apollo Client chosen for**:
-- Automatic normalization (User:123 cached once, shared across queries)
-- GraphQL-first with fragments, type policies, subscriptions
-- Field policies for data transformation/masking
-- Excellent DevTools
-
-**Trade-offs**:
-- Bundle size: 33 KB vs 5-13 KB for alternatives
-- Learning curve: normalization and cache keys
-- GraphQL-only (can't cache REST easily)
-
-**Rationale**: For GraphQL projects with complex data relationships, Apollo's normalized cache and GraphQL-specific features provide best DX and performance.
+## Considered Options / Areas of Research
 
 ### Cache Policies
 
 Apollo Client offers multiple fetch policies:
 
 #### cache-first (Default)
-Read from cache, fetch on cache miss. Best for static/public data.
-
-**Behavior**: Check cache first, only fetch if data not found
-
-**Use cases**: Product catalogs, blog posts, reference data
+Read from cache, fetch on cache miss. Best for static/public data. Useful for product catalogs, blog posts, reference data
 
 #### network-only
-Always fetch fresh, appropriate for sensitive data.
-
-**Behavior**: Always fetch from network, update cache but never read from it
-
-**Use cases**: Bank balances, private messages, real-time data
+Always fetch fresh (though update cache anyway), appropriate for sensitive data. Useful for bank balances, private messages, real-time data
 
 #### cache-and-network
-Show cached instantly, refresh in background.
-
-**Behavior**: Return cached data immediately, then fetch fresh and update
-
-**Use cases**: Social feeds, dashboards
+Show cached instantly, refresh in background. Useful for social feeds, dashboards
 
 #### no-cache
-Bypasses cache entirely for single-use data.
-
-**Behavior**: Fetch from network, don't read or write to cache
-
-**Use cases**: OTP codes, reset tokens
+Bypasses cache entirely for single-use data. Useful for OTP codes, reset tokens
 
 ### Field-Level Security
 
@@ -92,8 +58,6 @@ Use field policies to mask sensitive data even if server returns real values.
 - Read function returns masked value (e.g., '***-**-****')
 - Original server data never exposed in cache
 
-**Benefits**: Defense-in-depth, cache inspector safety, redacted logs
-
 ### Varying Field Selections
 
 Apollo merges queries with different fields into same cache entry.
@@ -101,37 +65,11 @@ Apollo merges queries with different fields into same cache entry.
 Query minimal fields first, then full profile:
 - Minimal query caches 3 fields
 - Full query merges 6 fields total
-- Subsequent minimal queries read all 6 from cache
-
-Key insight: Query broader fields first, narrower queries benefit from cache.
-
-### useFragment for Cache Reads
-
-Read cached data without network request.
-
-**Process:**
-- Component receives entity ID as prop
-- useFragment reads directly from cache using fragment definition
-- Returns complete flag (true if all fields available) and data
-- Component subscribes to cache updates for that entity
-
-**Benefits**: Zero network overhead, live updates, avoids prop drilling
-
-See [ADR 0024](./0024-usefragment-vs-httpbatch-dataloader.md) for re-render optimization details.
+- Subsequent minimal queries read all 6 from cache, eliminating excess entries
 
 ### Optimistic Updates
 
-Update UI instantly before server confirms mutation success.
-
-**Process:**
-1. User triggers mutation (e.g., like post)
-2. Client immediately updates cache with predicted response
-3. UI reflects change instantly
-4. Mutation sent to server
-5. On success: cache already correct
-6. On failure: Apollo automatically rolls back optimistic update
-
-**Use cases**: Likes, favorites, toggles
+Update UI instantly before server confirms mutation success. Useful for likes, favorites, toggles. Improves UX.
 
 **Optimistic Update Flow:**
 
@@ -160,11 +98,11 @@ sequenceDiagram
 
 ## Decision Outcome
 
-Chosen option: **Tiered caching strategy** based on data sensitivity and freshness requirements.
+**Tiered caching strategy** based on data sensitivity and freshness requirements.
 
-**Tier 1 - Public/Static (cache-first)**: Event listings, community pages, account plans
+**Tier 1 - Public/Static (cache-first)**: item listings, user profiles, account plans
 
-**Tier 2 - User-Specific (cache-and-network)**: User feeds, event attendance, notifications
+**Tier 2 - User-Specific (cache-and-network)**: User feeds
 
 **Tier 3 - Sensitive (network-only)**: Payment information, admin data, private messages
 
@@ -195,58 +133,23 @@ graph TD
     style F fill:#4f4
 ```
 
-### Implementation for ShareThrift
-
-**Configure Cache:**
-- Initialize InMemoryCache with type policies
-- Define key fields for entity identification (typically 'id')
-- Configure field policies for sensitive data masking
-- Example: Mask email field to always return redacted value
-
-**Apply Policies:**
-- **Public event listings**: `cache-first` for maximum caching
-- **User-specific feed**: `cache-and-network` for instant display with background refresh
-- **Payment information**: `network-only` to always fetch fresh, never cache
+## Technical Considerations
 
-## Cache Invalidation
+### Cache Invalidation Strategies
 
-### Refetch Queries
+Apollo Client provides three approaches for keeping cached data fresh after mutations. **refetchQueries** automatically re-executes specified queries after mutation completion by providing array of query names—simple but causes unnecessary network requests for all queries even if only subset affected. **Cache Eviction** manually removes entries by calling cache eviction methods to delete specific entity by identifier and garbage collect orphaned references—more precise than refetchQueries and avoids unnecessary network traffic. **Polling** periodically refetches query at fixed interval (e.g., every 5 seconds) for simple real-time updates on non-critical data—inefficient compared to GraphQL subscriptions and should only be used when subscriptions not feasible.
 
-Specify queries to automatically refetch after mutation completes.
-- Provide array of query names
-- Apollo automatically re-executes those queries
-- Simple but can cause unnecessary network requests
-
-### Cache Eviction
-
-Manually remove entries from cache after mutation.
-- Use `cache.evict()` to remove specific entity by ID
-- Use `cache.gc()` to garbage collect orphaned references
-- More precise than refetchQueries, avoids network requests
-
-### Polling (use sparingly)
-
-Periodically refetch query at fixed interval (e.g., every 5 seconds).
-- Simple real-time updates for non-critical data
-- Inefficient compared to subscriptions
-- Use only when subscriptions not feasible
+### Field-Level Security
 
-## Tooling and Debugging
+Apollo Client's field policies provide defense-in-depth by masking sensitive data even if server mistakenly returns real values. Configure type policies in InMemoryCache with custom read functions for sensitive fields (SSN, credit cards, passwords). The read function intercepts cache reads and returns masked values ensuring original server data never exposed in cache inspector, console logs, or debugging tools. This pattern protects against both server bugs and client-side inspection.
 
-### Apollo DevTools
-Chrome/Firefox extension for cache inspection, query tracking, mutation debugging
+### Cache Normalization and Field Selection
 
-### Browser Network Tab
-Filter by `graphql` to verify cache behavior:
-- cache-first: no network request after first fetch
-- network-only: always hits network
+Apollo automatically merges queries with different field selections into same cache entry. When component A queries minimal user fields and component B later queries full user profile with additional fields, Apollo merges all fields into single cache entry for that user. Subsequent queries for any subset of those fields read from cache without network request. Key insight: query broader field sets first to maximize cache utilization for narrower queries. This normalization eliminates data duplication across queries.
 
-### Cache Debugging
+### Debugging and Monitoring
 
-Extract entire cache contents for inspection.
-- Use `client.cache.extract()` to view all cached entities
-- Helpful for debugging unexpected cache behavior
-- Can log to console or use Apollo DevTools for visual inspection
+[Apollo DevTools](https://chromewebstore.google.com/detail/apollo-client-devtools/jdkknkkbebbapilgoeccciglkfbmbnfm) Chrome/Firefox extension provides visual cache inspection, query tracking, and mutation debugging. Use cache extraction methods to dump entire cache contents for debugging unexpected behavior—helpful for logging or console inspection. Monitor cache size in production (target: 10-50 MB) to prevent memory issues. Use browser network tab filtered by graphql to verify cache behavior: cache-first shows no network request after initial fetch, network-only always hits network.
 
 ## Consequences
 
@@ -260,6 +163,17 @@ Extract entire cache contents for inspection.
 - Bad, because large caches consume client memory (target: 10-50 MB)
 - Bad, because cache issues can be subtle to debug
 
+## Validation with Performance Testing
+
+Created a single test page to validate caching
+
+1. **Public Caching Test** ([ClientCacheDemo.tsx](https://github.com/jason-t-hankins/Social-Feed/blob/main/client/src/demos/05-client-cache/ClientCacheDemo.tsx))
+<br></br> Simplified demo focused on the key requirements:
+   1. Varying field selections and cache merge behavior
+   2. Public vs private data caching strategies
+   3. Cache inspection with Apollo DevTools
+   4. Field-level security (SSN masking)
+
 ## More Information
 
 - [Social-Feed Demo Application](https://github.com/jason-t-hankins/Social-Feed/)

From 4cdb4446c2acc2fe60cb134db37fb4ecfc543344 Mon Sep 17 00:00:00 2001
From: Jason Hankins <jason.hankins27@gmail.com>
Date: Thu, 18 Dec 2025 11:33:30 -0500
Subject: [PATCH 07/10] add description for client side tiered strategy
 decision

---
 apps/docs/docs/decisions/0027-client-side-caching.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/apps/docs/docs/decisions/0027-client-side-caching.md b/apps/docs/docs/decisions/0027-client-side-caching.md
index e1c9310bd..f89e19378 100644
--- a/apps/docs/docs/decisions/0027-client-side-caching.md
+++ b/apps/docs/docs/decisions/0027-client-side-caching.md
@@ -100,6 +100,8 @@ sequenceDiagram
 
 **Tiered caching strategy** based on data sensitivity and freshness requirements.
 
+A one-size-fits-all cache policy creates unacceptable tradeoffs—aggressive caching risks exposing sensitive data while conservative policies sacrifice performance gains. Instead, we adopt a tiered approach that matches cache behavior to data classification. This balances security requirements (never cache sensitive data) with performance optimization (maximize caching for safe data) while providing clear guidelines for developers to apply consistently across the application.
+
 **Tier 1 - Public/Static (cache-first)**: item listings, user profiles, account plans
 
 **Tier 2 - User-Specific (cache-and-network)**: User feeds

From 8adc17996197c33bee3ac731a2ce4277fab1d154 Mon Sep 17 00:00:00 2001
From: Jason Hankins <jason.hankins27@gmail.com>
Date: Fri, 19 Dec 2025 16:04:58 -0500
Subject: [PATCH 08/10] fix build errors from merge

---
 pnpm-lock.yaml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 248e11eda..a49a636fe 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -13464,6 +13464,25 @@ snapshots:
   '@biomejs/cli-win32-x64@2.0.0':
     optional: true
 
+  '@braintree/sanitize-url@7.1.1': {}
+
+  '@chevrotain/cst-dts-gen@11.0.3':
+    dependencies:
+      '@chevrotain/gast': 11.0.3
+      '@chevrotain/types': 11.0.3
+      lodash-es: 4.17.21
+
+  '@chevrotain/gast@11.0.3':
+    dependencies:
+      '@chevrotain/types': 11.0.3
+      lodash-es: 4.17.21
+
+  '@chevrotain/regexp-to-ast@11.0.3': {}
+
+  '@chevrotain/types@11.0.3': {}
+
+  '@chevrotain/utils@11.0.3': {}
+
   '@chromatic-com/storybook@4.1.2(storybook@9.1.17(@testing-library/dom@10.4.1)(vite@7.1.12(@types/node@24.9.2)(jiti@2.6.1)(lightningcss@1.30.2)(terser@5.44.0)(tsx@4.20.6)(yaml@2.8.1)))':
     dependencies:
       '@neoconfetti/react': 1.0.0

From 50d0097c0f378bdb9e3ee829bebad313bdeb3d7f Mon Sep 17 00:00:00 2001
From: Jason Hankins <jason.hankins27@gmail.com>
Date: Fri, 16 Jan 2026 15:29:47 -0500
Subject: [PATCH 09/10] fix merge conflict errors from lockfile

---
 pnpm-lock.yaml | 63 ++++++++++++++++++++++++++------------------------
 1 file changed, 33 insertions(+), 30 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a6d5a8541..76708e51d 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -198,10 +198,10 @@ importers:
         version: 3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.8.3)
       '@docusaurus/preset-classic':
         specifier: 3.9.2
-        version: 3.9.2(@algolia/client-search@5.41.0)(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(@types/react@19.2.2)(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(search-insights@2.17.3)(typescript@5.6.3)
+        version: 3.9.2(@algolia/client-search@5.41.0)(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(@types/react@19.2.2)(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(search-insights@2.17.3)(typescript@5.8.3)
       '@docusaurus/theme-mermaid':
         specifier: ^3.9.2
-        version: 3.9.2(@docusaurus/plugin-content-docs@3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3))(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3)
+        version: 3.9.2(@docusaurus/plugin-content-docs@3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.8.3))(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.8.3)
       '@mdx-js/react':
         specifier: ^3.0.0
         version: 3.1.1(@types/react@19.2.2)(react@19.2.0)
@@ -9801,14 +9801,15 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  pngjs@7.0.0:
+    resolution: {integrity: sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==}
+    engines: {node: '>=14.19.0'}
+
   points-on-curve@0.2.0:
     resolution: {integrity: sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==}
 
   points-on-path@0.2.1:
     resolution: {integrity: sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g==}
-  pngjs@7.0.0:
-    resolution: {integrity: sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==}
-    engines: {node: '>=14.19.0'}
 
   possible-typed-array-names@1.1.0:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
@@ -12165,25 +12166,6 @@ packages:
       jsdom:
         optional: true
 
-  vscode-jsonrpc@8.2.0:
-    resolution: {integrity: sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==}
-    engines: {node: '>=14.0.0'}
-
-  vscode-languageserver-protocol@3.17.5:
-    resolution: {integrity: sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==}
-
-  vscode-languageserver-textdocument@1.0.12:
-    resolution: {integrity: sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==}
-
-  vscode-languageserver-types@3.17.5:
-    resolution: {integrity: sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==}
-
-  vscode-languageserver@9.0.1:
-    resolution: {integrity: sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==}
-    hasBin: true
-
-  vscode-uri@3.0.8:
-    resolution: {integrity: sha512-AyFQ0EVmsOZOlAnxoFOGOq1SQDWAB7C6aqMGS23svWAllfOaxbuFvcT8D1i8z3Gyn8fraVeZNNmN6e9bxxXkKw==}
   vitest@4.0.15:
     resolution: {integrity: sha512-n1RxDp8UJm6N0IbJLQo+yzLZ2sQCDyl1o0LeugbPWf8+8Fttp29GghsQBjYJVmWq3gBFfe9Hs1spR44vovn2wA==}
     engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0}
@@ -12218,6 +12200,26 @@ packages:
       jsdom:
         optional: true
 
+  vscode-jsonrpc@8.2.0:
+    resolution: {integrity: sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==}
+    engines: {node: '>=14.0.0'}
+
+  vscode-languageserver-protocol@3.17.5:
+    resolution: {integrity: sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==}
+
+  vscode-languageserver-textdocument@1.0.12:
+    resolution: {integrity: sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==}
+
+  vscode-languageserver-types@3.17.5:
+    resolution: {integrity: sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==}
+
+  vscode-languageserver@9.0.1:
+    resolution: {integrity: sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==}
+    hasBin: true
+
+  vscode-uri@3.0.8:
+    resolution: {integrity: sha512-AyFQ0EVmsOZOlAnxoFOGOq1SQDWAB7C6aqMGS23svWAllfOaxbuFvcT8D1i8z3Gyn8fraVeZNNmN6e9bxxXkKw==}
+
   w3c-xmlserializer@5.0.0:
     resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==}
     engines: {node: '>=18'}
@@ -13943,7 +13945,7 @@ snapshots:
 
   '@chevrotain/utils@11.0.3': {}
 
-  '@chromatic-com/storybook@4.1.2(storybook@9.1.17(@testing-library/dom@10.4.1)(vite@7.1.12(@types/node@24.9.2)(jiti@2.6.1)(lightningcss@1.30.2)(terser@5.44.0)(tsx@4.20.6)(yaml@2.8.1)))':
+  '@chromatic-com/storybook@4.1.2(storybook@9.1.17(@testing-library/dom@10.4.1)(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(terser@5.44.0)(tsx@4.20.6)(yaml@2.8.1)))':
     dependencies:
       '@neoconfetti/react': 1.0.0
       chromatic: 12.2.0
@@ -15030,11 +15032,11 @@ snapshots:
       - uglify-js
       - webpack-cli
 
-  '@docusaurus/theme-mermaid@3.9.2(@docusaurus/plugin-content-docs@3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3))(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3)':
+  '@docusaurus/theme-mermaid@3.9.2(@docusaurus/plugin-content-docs@3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.8.3))(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.8.3)':
     dependencies:
-      '@docusaurus/core': 3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3)
+      '@docusaurus/core': 3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.8.3)
       '@docusaurus/module-type-aliases': 3.9.2(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
-      '@docusaurus/theme-common': 3.9.2(@docusaurus/plugin-content-docs@3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.6.3))(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
+      '@docusaurus/theme-common': 3.9.2(@docusaurus/plugin-content-docs@3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.8.3))(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
       '@docusaurus/types': 3.9.2(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
       '@docusaurus/utils-validation': 3.9.2(react-dom@19.2.0(react@19.2.0))(react@19.2.0)
       mermaid: 11.12.2
@@ -15060,7 +15062,7 @@ snapshots:
       - utf-8-validate
       - webpack-cli
 
-  '@docusaurus/theme-search-algolia@3.9.2(@algolia/client-search@5.41.0)(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(@types/react@19.2.2)(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(search-insights@2.17.3)(typescript@5.6.3)':
+  '@docusaurus/theme-search-algolia@3.9.2(@algolia/client-search@5.41.0)(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(@types/react@19.2.2)(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(search-insights@2.17.3)(typescript@5.8.3)':
     dependencies:
       '@docsearch/react': 3.9.0(@algolia/client-search@5.41.0)(@types/react@19.2.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(search-insights@2.17.3)
       '@docusaurus/core': 3.9.2(@mdx-js/react@3.1.1(@types/react@19.2.2)(react@19.2.0))(lightningcss@1.30.2)(react-dom@19.2.0(react@19.2.0))(react@19.2.0)(typescript@5.8.3)
@@ -23291,13 +23293,14 @@ snapshots:
     optionalDependencies:
       fsevents: 2.3.2
 
+  pngjs@7.0.0: {}
+
   points-on-curve@0.2.0: {}
 
   points-on-path@0.2.1:
     dependencies:
       path-data-parser: 0.1.0
       points-on-curve: 0.2.0
-  pngjs@7.0.0: {}
 
   possible-typed-array-names@1.1.0: {}
 

From 11d81b308bb2712912dea9907c691faeb106295c Mon Sep 17 00:00:00 2001
From: Jason Hankins <jason.hankins27@gmail.com>
Date: Tue, 20 Jan 2026 13:28:15 -0500
Subject: [PATCH 10/10] upgrade azure functions

---
 apps/api/package.json                 |  2 +-
 packages/sthrift/graphql/package.json |  2 +-
 packages/sthrift/rest/package.json    |  2 +-
 pnpm-lock.yaml                        | 34 +++++++++++++++++----------
 4 files changed, 24 insertions(+), 16 deletions(-)

diff --git a/apps/api/package.json b/apps/api/package.json
index 141fb4f17..ce996e341 100644
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -20,7 +20,7 @@
 		"azurite": "azurite-blob --silent --location ../../__blobstorage__ & azurite-queue --silent --location ../../__queuestorage__ & azurite-table --silent --location ../../__tablestorage__"
 	},
 	"dependencies": {
-		"@azure/functions": "^4.0.0",
+		"@azure/functions": "^4.11.0",
 		"@cellix/api-services-spec": "workspace:*",
 		"@cellix/messaging-service": "workspace:*",
 		"@cellix/mongoose-seedwork": "workspace:*",
diff --git a/packages/sthrift/graphql/package.json b/packages/sthrift/graphql/package.json
index 022168d18..e0a6bbaa1 100644
--- a/packages/sthrift/graphql/package.json
+++ b/packages/sthrift/graphql/package.json
@@ -27,7 +27,7 @@
 		"@apollo/server": "^5.2.0",
 		"@apollo/utils.withrequired": "^3.0.0",
 		"@as-integrations/azure-functions": "^0.2.0",
-		"@azure/functions": "^4.0.0",
+		"@azure/functions": "^4.11.0",
 		"@graphql-tools/json-file-loader": "^8.0.20",
 		"@graphql-tools/load": "^8.1.2",
 		"@graphql-tools/load-files": "^7.0.1",
diff --git a/packages/sthrift/rest/package.json b/packages/sthrift/rest/package.json
index bdf0f7187..0442161f5 100644
--- a/packages/sthrift/rest/package.json
+++ b/packages/sthrift/rest/package.json
@@ -20,7 +20,7 @@
 		"clean": "rimraf dist"
 	},
 	"dependencies": {
-		"@azure/functions": "^4.6.0",
+		"@azure/functions": "^4.11.0",
 		"typescript": "^5.8.3",
 		"@sthrift/application-services": "workspace:*"
 	},
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 76708e51d..022efe668 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -118,8 +118,8 @@ importers:
   apps/api:
     dependencies:
       '@azure/functions':
-        specifier: ^4.0.0
-        version: 4.8.0
+        specifier: ^4.11.0
+        version: 4.11.0
       '@cellix/api-services-spec':
         specifier: workspace:*
         version: link:../../packages/cellix/api-services-spec
@@ -835,8 +835,8 @@ importers:
         specifier: ^0.2.0
         version: 0.2.2(@apollo/server@5.2.0(graphql@16.11.0))
       '@azure/functions':
-        specifier: ^4.0.0
-        version: 4.8.0
+        specifier: ^4.11.0
+        version: 4.11.0
       '@graphql-tools/json-file-loader':
         specifier: ^8.0.20
         version: 8.0.20(graphql@16.11.0)
@@ -1122,8 +1122,8 @@ importers:
   packages/sthrift/rest:
     dependencies:
       '@azure/functions':
-        specifier: ^4.6.0
-        version: 4.8.0
+        specifier: ^4.11.0
+        version: 4.11.0
       '@sthrift/application-services':
         specifier: workspace:*
         version: link:../application-services
@@ -1694,6 +1694,10 @@ packages:
     resolution: {integrity: sha512-XPArKLzsvl0Hf0CaGyKHUyVgF7oDnhKoP85Xv6M4StF/1AhfORhZudHtOyf2s+FcbuQ9dPRAjB8J2KvRRMUK2A==}
     engines: {node: '>=20.0.0'}
 
+  '@azure/functions-extensions-base@0.2.0':
+    resolution: {integrity: sha512-ncCkHBNQYJa93dBIh+toH0v1iSgCzSo9tr94s6SMBe7DPWREkaWh8cq33A5P4rPSFX1g5W+3SPvIzDr/6/VOWQ==}
+    engines: {node: '>=18.0'}
+
   '@azure/functions-opentelemetry-instrumentation@0.1.0':
     resolution: {integrity: sha512-eRitTbOUDhlzc4o2Q9rjbXiMYa/ep06m2jIkN7HOuLP0aHnjPh3zHXtqji/NyeqT/GfHjCgJr+r8+49s7KER7w==}
     engines: {node: '>=18.0'}
@@ -1703,9 +1707,9 @@ packages:
   '@azure/functions@3.5.1':
     resolution: {integrity: sha512-6UltvJiuVpvHSwLcK/Zc6NfUwlkDLOFFx97BHCJzlWNsfiWwzwmTsxJXg4kE/LemKTHxPpfoPE+kOJ8hAdiKFQ==}
 
-  '@azure/functions@4.8.0':
-    resolution: {integrity: sha512-LNtl3xZNE40vE7+SIST+GYQX5cnnI1M65fXPi26l9XCdPakuQrz54lHv+qQQt1GG5JbqLfQk75iM7A6Y9O+2dQ==}
-    engines: {node: '>=18.0'}
+  '@azure/functions@4.11.0':
+    resolution: {integrity: sha512-J0We2gav3YZFLO9pJlXDKUSOT0r/DzkUaJTaruhm8pwoSMbi4zjsS5N6fARrTel+IBCm77hlD0IgZSKSWvVpUw==}
+    engines: {node: '>=20.0'}
 
   '@azure/identity@3.4.2':
     resolution: {integrity: sha512-0q5DL4uyR0EZ4RXQKD8MadGH6zTIcloUoS/RVbCpNpej4pwte0xpqYxk8K97Py2RiuUvI7F4GXpoT4046VfufA==}
@@ -12881,7 +12885,7 @@ snapshots:
     dependencies:
       '@apollo/server': 5.2.0(graphql@16.11.0)
       '@azure/functions': 3.5.1
-      '@azure/functions-v4': '@azure/functions@4.8.0'
+      '@azure/functions-v4': '@azure/functions@4.11.0'
 
   '@asamuzakjp/css-color@3.2.0':
     dependencies:
@@ -12996,6 +13000,8 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  '@azure/functions-extensions-base@0.2.0': {}
+
   '@azure/functions-opentelemetry-instrumentation@0.1.0(@opentelemetry/api@1.9.0)':
     dependencies:
       '@opentelemetry/api': 1.9.0
@@ -13009,11 +13015,11 @@ snapshots:
       long: 4.0.0
       uuid: 8.3.2
 
-  '@azure/functions@4.8.0':
+  '@azure/functions@4.11.0':
     dependencies:
+      '@azure/functions-extensions-base': 0.2.0
       cookie: 0.7.2
       long: 4.0.0
-      undici: 5.29.0
 
   '@azure/identity@3.4.2':
     dependencies:
@@ -15514,7 +15520,8 @@ snapshots:
       '@eslint/core': 0.17.0
       levn: 0.4.1
 
-  '@fastify/busboy@2.1.1': {}
+  '@fastify/busboy@2.1.1':
+    optional: true
 
   '@fastify/busboy@3.2.0': {}
 
@@ -25718,6 +25725,7 @@ snapshots:
   undici@5.29.0:
     dependencies:
       '@fastify/busboy': 2.1.1
+    optional: true
 
   unicode-canonical-property-names-ecmascript@2.0.1: {}