resolutionflow/docs/architecture/god-node-report-2026-05-06.md

title, date, tags

title	date	tags
God Node Architecture Report	2026-05-06	architecture dependency-graph god-nodes

God Node Architecture Report — 2026-05-06

Summary

This is a static dependency and churn report for backend/app and frontend/src.

The main finding: ResolutionFlow has several expected infrastructure hubs, plus a smaller set of behavioral hubs that deserve care when touched. The highest-risk candidates are not the most-imported files; they are the files that combine high size, high churn, and many outbound dependencies.

Highest-risk behavioral hubs:

1. frontend/src/pages/AssistantChatPage.tsx
2. frontend/src/pages/TreeNavigationPage.tsx
3. frontend/src/pages/ProceduralNavigationPage.tsx
4. backend/app/services/flowpilot_engine.py
5. backend/app/api/endpoints/ai_sessions.py
6. backend/app/api/endpoints/sessions.py
7. backend/app/api/endpoints/trees.py
8. backend/app/api/endpoints/admin.py

Expected infrastructure hubs:

• frontend/src/lib/utils.ts
• frontend/src/types/index.ts
• frontend/src/api/index.ts
• frontend/src/api/client.ts
• frontend/src/lib/toast.ts
• backend/app/core/database.py
• backend/app/api/deps.py
• backend/app/core/config.py
• SQLAlchemy models such as User, Tree, AISession, and Account

Do not treat all high-degree nodes as bad. A utility, type barrel, API barrel, router, or ORM model can be central by design. The suspicious shape is: high outbound dependencies + high churn + large file + multiple unrelated reasons to change.

Method

Inputs:

• Source files: backend/app/**/*.py, frontend/src/**/*.ts, frontend/src/**/*.tsx
• Excluded: tests, docs, migrations, build output, env files
• Static imports:
  • Python: regex import extraction for import ... and from ... import ...
  • TypeScript/TSX: static import/export from plus dynamic import(...)
• Churn: git log --name-only --since='90 days ago'
• Size: line count

Scoring used for triage, not truth:

score = inbound_edges * 2
      + outbound_edges * 1.5
      + min(churn_90d, 30) * 1.2
      + min(lines_of_code / 100, 20)

Caveats:

• backend/app/__init__.py appears as a very high inbound node because static imports through app.* resolve through the package root in this simple parser. Ignore it as a parser artifact.
• Barrel files (frontend/src/api/index.ts, frontend/src/types/index.ts) intentionally create cycles with the modules they export. This is a known TypeScript graph artifact, not automatically a design flaw.
• Static graphs do not show runtime call volume. This report answers “where is the code structurally central?” not “what is hot in production?”

Visual Map

Primary visualization:

• Open docs/architecture/god-node-map-2026-05-06.canvas in Obsidian.
• This uses Obsidian Canvas, so no community plugin is required.
• The Canvas groups nodes by interpretation instead of drawing every import edge.

The dense dependency graph is intentionally not the default view anymore. For architecture review, the useful split is:

1. Which nodes are high-risk behavioral hubs?
2. Which central nodes are expected infrastructure?
3. What should self-serve signup avoid touching?

Risk Overview

flowchart LR
  Work["Self-serve signup work"] --> Boundaries["Keep changes at boundaries"]
  Boundaries --> BillingStore["useBillingStore"]
  Boundaries --> Guards["router/dependency guards"]
  Boundaries --> BillingService["BillingService"]

  Assistant["AssistantChatPage.tsx\nfrontend god node"] -. avoid unrelated edits .-> Work
  FlowPilot["flowpilot_engine.py\nbackend god node"] -. avoid unrelated edits .-> Work
  AISessions["ai_sessions.py\ncontroller + mapper"] -. do not add billing logic .-> Work
  SessionsTrees["sessions.py / trees.py\nlarge endpoint hubs"] -. mount guards, avoid handler sprawl .-> Work

  Utils["utils / toast / api client / database\nexpected infrastructure"] -. do not refactor just because central .-> Work

Frontend Hotspots

flowchart TB
  Router["router.tsx\nroute hub"] --> Assistant["AssistantChatPage.tsx\nhighest risk"]
  Router --> TreeNav["TreeNavigationPage.tsx"]
  Router --> ProcNav["ProceduralNavigationPage.tsx"]
  Router --> TreeLibrary["TreeLibraryPage.tsx"]
  Router --> TreeEditor["TreeEditorPage.tsx"]
  Router --> SessionDetail["SessionDetailPage.tsx"]

  Assistant --> ExtractA["Extract one workflow at a time"]
  TreeNav --> ExtractB["Extract orchestration hooks when touched"]
  ProcNav --> ExtractB

  Infra["utils.ts / toast.ts / api/client.ts / types/index.ts"]
  Assistant --> Infra
  TreeNav --> Infra
  ProcNav --> Infra

Backend Hotspots

flowchart TB
  Deps["api/deps.py\nboundary hub"] --> DB["database + models\nexpected infrastructure"]

  AISessions["api/endpoints/ai_sessions.py"] --> FlowPilot["services/flowpilot_engine.py"]
  Sessions["api/endpoints/sessions.py"] --> Export["services/export_service.py"]
  Trees["api/endpoints/trees.py"] --> DB
  Admin["api/endpoints/admin.py"] --> DB

  SelfServe["Self-serve backend"] --> Deps
  SelfServe --> Billing["BillingService + subscriptions"]
  SelfServe -. avoid .-> AISessions
  SelfServe -. avoid .-> Sessions
  SelfServe -. avoid .-> Trees
  SelfServe -. avoid .-> FlowPilot

Obsidian Visualization Options

Best default: use the generated Canvas file. Obsidian Canvas is a core plugin and stores diagrams as .canvas files, so it works without adding community plugin risk.

Optional plugins worth considering:

• Excalidraw: best if you want hand-edited architecture diagrams that feel like a whiteboard.
• Markmind: useful if you want this report as a mind map or outline-first view.
• Diagrams.net / draw.io plugin: useful for formal boxes-and-arrows diagrams, but heavier than Canvas for this use case.

Recommendation: start with Canvas. Add Excalidraw only if you want to manually sketch over the architecture map during planning sessions.

Top Centrality Candidates

Rank	File	In	Out	90d churn	LOC	Classification	Read
1	frontend/src/lib/utils.ts	225	0	1	32	Infrastructure hub	Good
2	frontend/src/types/index.ts	137	32	22	103	Barrel hub	Watch
3	backend/app/core/database.py	110	2	2	47	Infrastructure hub	Good
4	backend/app/models/user.py	90	7	13	130	Domain model hub	Watch
5	frontend/src/api/index.ts	38	40	26	41	API barrel hub	Watch
6	frontend/src/lib/toast.ts	79	0	1	72	Infrastructure hub	Good
7	frontend/src/router.tsx	1	72	48	308	Router hub	Watch
8	backend/app/api/deps.py	56	9	13	292	Auth/dependency hub	Watch
9	backend/app/core/config.py	44	1	27	232	Config hub	Good, but churny
10	frontend/src/pages/AssistantChatPage.tsx	2	39	77	2493	Behavioral hub	High risk
11	backend/app/models/tree.py	43	10	11	233	Domain model hub	Watch
12	frontend/src/api/client.ts	51	2	5	173	API client hub	Good
13	frontend/src/pages/TreeNavigationPage.tsx	2	31	33	1385	Behavioral hub	High risk
14	frontend/src/components/ui/Button.tsx	43	2	6	65	UI primitive	Good
15	backend/app/models/ai_session.py	32	11	11	314	Domain model hub	Watch
16	frontend/src/pages/ProceduralNavigationPage.tsx	1	33	22	1021	Behavioral hub	High risk
17	frontend/src/pages/TreeLibraryPage.tsx	3	27	38	546	Behavioral hub	Medium risk
18	backend/app/models/account.py	29	11	8	70	Domain model hub	Watch
19	backend/app/api/endpoints/sessions.py	0	24	26	1186	Endpoint hub	High risk
20	frontend/src/pages/TreeEditorPage.tsx	2	20	28	928	Behavioral hub	Medium risk
21	frontend/src/pages/SessionDetailPage.tsx	2	21	28	623	Behavioral hub	Medium risk
22	backend/app/api/endpoints/trees.py	0	20	23	1332	Endpoint hub	High risk
23	backend/app/api/endpoints/ai_sessions.py	0	15	32	1173	Endpoint hub	High risk
24	backend/app/services/flowpilot_engine.py	1	17	20	1793	Behavioral service hub	High risk

Findings

1. AssistantChatPage.tsx Is The Clearest Frontend God Node

Evidence:

• 2,493 LOC
• 39 outbound dependencies
• 77 changes in 90 days
• Owns routing, chat selection, magic-moment pickup state, task-lane state, upload state, facts, suggested fixes, preview state, script-builder surfaces, modals, keyboard shortcuts, local/session storage, and message rendering orchestration.

Classification: behavioral god node.

This file has too many reasons to change. It is not dangerous because many files import it; it is dangerous because it imports many things, owns many workflows, and changes constantly.

Recommended response:

• Do not do a broad refactor in isolation.
• When touching it, extract one workflow at a time behind a hook or controller:
  • useTaskLaneState
  • usePilotPickup
  • useSuggestedFixPreview
  • useSessionFacts
  • useScriptBuilderPanelState
• Keep the page as an orchestrator, but move state machines and async effects out.
• Before major changes, add narrow regression tests around task-lane ownership and session switching.

Priority: high, opportunistic refactor.

2. flowpilot_engine.py Is A Real Backend Behavioral Hub

Evidence:

• 1,793 LOC
• 17 outbound dependencies
• 20 changes in 90 days
• Owns prompts, structured output parsing, session start, step generation, confidence, close/resolve/escalate behaviors, and likely several persistence transitions.

Classification: behavioral service hub.

This is not surprising: FlowPilot is core product logic. The risk is that prompt text, model call orchestration, persistence, and business rules live close together.

Recommended response:

• Keep this file stable during unrelated work.
• Extract only when a change naturally creates a seam:
  • prompt construction
  • structured output validation
  • session state transition persistence
  • documentation/status update generation
• Avoid routing new self-serve billing or account logic through this service.

Priority: high, but avoid speculative refactor.

3. AI Session Endpoint Is Acting As A Controller Plus Mapper

File: backend/app/api/endpoints/ai_sessions.py

Evidence:

• 1,173 LOC
• 15 outbound dependencies
• 32 changes in 90 days
• Contains endpoint handlers, quota checks, response mapping, ownership behavior, chat wiring, and PSA retry integration.

Classification: endpoint god node.

The endpoint does more than route HTTP to services. Some helper logic is fine, but the mapper and ownership rules should stay stable and test-backed.

Recommended response:

• Keep endpoint handlers thin when adding new features.
• Move reusable mapping logic such as _build_session_detail to a schema/service helper if it is touched again.
• Do not add subscription or onboarding behavior directly here; mount dependencies at router level where possible.

Priority: high for change discipline, medium for refactor.

4. Classic Session And Tree Endpoints Are Large, But Mostly Expected

Files:

• backend/app/api/endpoints/sessions.py
• backend/app/api/endpoints/trees.py

Evidence:

• sessions.py: 1,186 LOC, 24 outbound dependencies, 26 changes
• trees.py: 1,332 LOC, 20 outbound dependencies, 23 changes

Classification: endpoint hubs.

These files are not surprising in a CRUD-heavy FastAPI app, but they are large enough that behavioral additions should be routed through services or focused helpers.

Recommended response:

• For new subscription guards, mount dependencies instead of inserting repeated checks inside handlers.
• For new tree/session behavior, prefer service functions over adding more endpoint-local logic.
• Add regression tests before modifying export, sharing, ownership, or limit-check paths.

Priority: medium-high.

5. Frontend Page-Level Hubs Are The Main UI Risk

Files:

• frontend/src/pages/TreeNavigationPage.tsx
• frontend/src/pages/ProceduralNavigationPage.tsx
• frontend/src/pages/TreeLibraryPage.tsx
• frontend/src/pages/TreeEditorPage.tsx
• frontend/src/pages/SessionDetailPage.tsx

Pattern:

• High outbound dependencies
• Meaningful churn
• Page components own orchestration plus rendering

Recommended response:

• Treat page components as shells where possible.
• Extract stable workflow hooks before adding another workflow.
• Keep design updates scoped to subcomponents.
• Avoid adding global state unless the state truly spans routes.

Priority: medium, with TreeNavigationPage.tsx and ProceduralNavigationPage.tsx highest.

6. Auth Store Is Central But Not Yet A Problem

File: frontend/src/store/authStore.ts

Evidence:

• 21 inbound dependencies
• 5 outbound dependencies
• 144 LOC
• 6 changes in 90 days

Classification: central state hub.

This is a normal app hub. It becomes risky if billing, onboarding, feature gates, and auth all accumulate here. The self-serve spec’s choice to create useBillingStore instead of embedding billing state in /auth/me is the right architectural direction.

Recommended response:

• Keep auth store focused on identity/session/account bootstrap.
• Put billing in useBillingStore.
• Put onboarding wizard state in a narrow API/hook, not in auth.

Priority: watch.

7. Barrels Are Creating A Large Frontend Cycle

Cycle:

• 42 files under frontend/src/api/*
• Driven by frontend/src/api/index.ts exporting modules while some modules import from the barrel or share apiClient.

Classification: barrel cycle / tooling artifact with some real coupling risk.

This is common and not urgent. It can confuse static tools and make imports less explicit.

Recommended response:

• Prefer direct imports from concrete API modules in new code:
  • Good: import { aiSessionsApi } from '@/api/aiSessions'
  • Avoid: import { aiSessionsApi } from '@/api'
• Keep api/index.ts only for broad convenience if it remains useful.
• Do not spend time untangling old imports unless dependency tooling starts enforcing boundaries.

Priority: low.

8. Backend ORM Model Cycles Are Expected

Cycle:

• 17 files across account/user/tree/session/subscription/category/share models
• 5 files across AI session branch/handoff/step models

Classification: SQLAlchemy relationship cycle.

This is expected in an ORM with bidirectional relationships. It does not mean the model layer is broken.

Recommended response:

• Keep imports guarded with TYPE_CHECKING where possible.
• Keep model methods thin.
• Put behavior in services, not model properties beyond simple derived flags.

Priority: low.

Ranked Action List

Do Now

No immediate large refactor is recommended before self-serve signup work. The report does not show a blocker.

Do During Self-Serve Work

1. Keep useBillingStore separate from authStore.
2. Mount subscription and email verification guards at router/dependency boundaries, not inside individual endpoint handlers.
3. Keep new billing service behavior out of existing ai_sessions.py, sessions.py, and trees.py except for dependency wiring.
4. Prefer direct frontend API imports over @/api barrel imports in new code.

Do Opportunistically

1. Extract one workflow at a time from AssistantChatPage.tsx.
2. Extract prompt construction or structured response validation from flowpilot_engine.py when touched.
3. Move response mapping helpers out of ai_sessions.py if those helpers change again.
4. Split page-level orchestration hooks out of TreeNavigationPage.tsx and ProceduralNavigationPage.tsx as features touch them.

Avoid

1. Do not split utils.ts, toast.ts, api/client.ts, or core/database.py just because they are central.
2. Do not refactor ORM model cycles unless they cause import/runtime issues.
3. Do not start a broad barrel-file cleanup unless tooling or build performance requires it.

Raw Metrics Snapshot

Total analyzed files: 783
Total static import edges: 2,946

Top inbound hubs:

File	Inbound	Outbound	90d churn	LOC	Note
frontend/src/lib/utils.ts	225	0	1	32	Healthy utility hub
frontend/src/types/index.ts	137	32	22	103	Barrel hub
backend/app/core/database.py	110	2	2	47	Healthy infrastructure hub
backend/app/models/user.py	90	7	13	130	Domain model hub
frontend/src/lib/toast.ts	79	0	1	72	Healthy utility hub
backend/app/api/deps.py	56	9	13	292	Auth/dependency hub
frontend/src/api/client.ts	51	2	5	173	API infrastructure hub
backend/app/core/config.py	44	1	27	232	Config hub, high churn
backend/app/models/tree.py	43	10	11	233	Domain model hub
frontend/src/components/ui/Button.tsx	43	2	6	65	UI primitive

Top outbound hubs:

File	Inbound	Outbound	90d churn	LOC	Note
frontend/src/router.tsx	1	72	48	308	Router hub, acceptable
frontend/src/api/index.ts	38	40	26	41	Barrel hub
frontend/src/pages/AssistantChatPage.tsx	2	39	77	2493	High-risk behavioral hub
frontend/src/pages/ProceduralNavigationPage.tsx	1	33	22	1021	High-risk behavioral hub
frontend/src/pages/TreeNavigationPage.tsx	2	31	33	1385	High-risk behavioral hub
frontend/src/pages/TreeLibraryPage.tsx	3	27	38	546	Medium-risk page hub
backend/app/api/endpoints/sessions.py	0	24	26	1186	High-risk endpoint hub
backend/app/api/endpoints/admin.py	0	22	10	1430	Admin endpoint hub
frontend/src/pages/SessionDetailPage.tsx	2	21	28	623	Medium-risk page hub
backend/app/api/endpoints/auth.py	0	20	9	721	Auth endpoint hub
backend/app/api/endpoints/trees.py	0	20	23	1332	High-risk endpoint hub
frontend/src/pages/ProceduralEditorPage.tsx	1	20	16	475	Medium-risk page hub
frontend/src/pages/TreeEditorPage.tsx	2	20	28	928	Medium-risk page hub

Detected cycles:

Size	Area	Interpretation
42	frontend/src/api/*	Barrel/export cycle. Low urgency.
17	backend ORM models	Expected SQLAlchemy relationship cycle. Low urgency.
5	backend AI session models	Expected relationship cycle. Low urgency.
2	tree preview components	Small component cycle; inspect only if these files become troublesome.

How To Re-run

The current environment does not have native Python, so this report was generated with Node-based static parsing plus shell/git commands. A future repeat can use a dedicated script if this becomes a regular architecture check.

Suggested future command shape:

node scripts/architecture/god-node-report.mjs

If this becomes a recurring check, add:

• scripts/architecture/god-node-report.mjs
• docs/architecture/god-node-report-YYYY-MM-DD.md
• optional docs/architecture/god-node-graph-YYYY-MM-DD.mmd