Project_Velocity/.Agent Context/Bibels/Sourik Code Intake and Compatibility Report.md

# Sourik Code Intake and Compatibility Report

**Prepared:** 2026-04-12  
**Scope:** `Project_Velocity/Sourik` only, evaluated against the current non-`Sourik` Project Velocity codebase, built features, and live operating model  
**Purpose:** Decide what from `Sourik` is worth merging, what is redundant, what is bloat, and where the conflicts will be

---

## Scoring Model

| Score | Meaning |
| --- | --- |
| 1 | Banish. Do not merge into main. |
| 2 | Archive only. Historical value, no production merge value. |
| 3 | Very weak merge candidate. Requires heavy rewrite or extraction. |
| 4 | Risky or partial. Import only if a specific owner adopts it. |
| 5 | Mixed value. Keep for reference, not direct merge. |
| 6 | Useful implementation ideas, but not merge-ready. |
| 7 | Good candidate for selective integration. |
| 8 | Strong subsystem candidate. |
| 9 | High-value, near-merge-ready if wiring assumptions are corrected. |
| 10 | Critical import candidate. No direct equivalent or materially better than current mainline. |

---

## Executive Summary

The `Sourik` tree is not one clean feature branch. It is a mixed bundle of:

- real backend/API work
- a separate Go agent runtime
- frontend additions for marketing and analytics
- a partial iOS spike
- strong test evidence in some areas
- large amounts of residue:
  - local env files
  - coverage outputs
  - compiled binaries
  - sqlite prototypes
  - pycache
  - logs
  - duplicate docs

The correct merge posture is:

- **do not merge the tree wholesale**
- **extract selected subsystems**
- **banish operational residue**
- **treat the Go runtime as an alternate architecture, not as an automatic addition**

Highest-value areas in `Sourik`:

- Python API modules around leads, persona, analytics, websocket, kanban, and Sentinel consent/GDPR patterns
- test coverage and test cases
- some Catalyst service abstractions
- some iOS camera/time-light experiment code

Highest-risk areas:

- duplicate backend entrypoint and alternate runtime model
- alternate Nemoclaw + MCP + Go server stack
- hardcoded stale infrastructure assumptions
- local SQLite-first assumptions that conflict with current PostgreSQL truth
- Comfy service hardcoded to stale IPs

---

## What Sourik Actually Contains

### Implementation Shape

`Sourik/velocity` contains:

- Python FastAPI app:
  - `main.py`
  - `api/*.py`
  - `services/*.py`
  - `db/connection.py`
- Go runtime:
  - `main.go`
  - `internal/nemoclaw/*`
  - `internal/oracle/*`
  - `internal/mcp/*`
  - `internal/sentinel/*`
  - `integrations/*.go`
- frontend additions:
  - `frontend/src/app/marketing/page.tsx`
  - `frontend/src/lib/api.ts`
  - dashboard/marketing components
- iOS spike:
  - `VelocityApp/*`
- docs and summaries:
  - `README.md`
  - `SPRINT_SUMMARY_FOR_SAGNIK.md`
  - `SPEC.md`
  - `docs/*`
- residue:
  - `.env`
  - `prototype.db`
  - coverage outputs
  - binaries
  - logs
  - pycache

### Sourik Architecture According to Sourik

The root `README.md` describes an “Agentic Operations Layer” with:

- WhatsApp webhook
- Go OpenClaw/NemoClaw layer
- MCP server
- ComfyUI / CRM / visual hub integrations

That is a materially different center-of-gravity from the current mainline, where:

- FastAPI backend is the operational center
- Linux control surface and ingress are already live
- Comfy routing and AWS orchestration are already established

This matters. `Sourik` is not just “new features.” It contains an alternate operating model.

---

## Compatibility with Current Mainline

### Current Mainline Truth

The non-`Sourik` codebase already has:

- a live FastAPI backend in `backend/main.py`
- active routers for Sentinel, CCTV, videos, scenes, vault
- a real Nemoclaw client abstraction in Python
- an Oracle implementation path in `backend/oracle/*`
- a premium React app in `app/src/*`
- a live ingress plane in `infrastructure/desineuron_ingress/*`
- a live Linux AWS control surface in `infrastructure/ops_control_plane/*`
- a real iOS app tree in `iOS/velocity/velocity/*`

So the comparison baseline is not theoretical. It is a partially working system with live infrastructure.

### Main Compatibility Findings

| Sourik Area | Mainline Equivalent | Compatibility |
| --- | --- | --- |
| `velocity/api/leads.py` | no equally complete current leads CRUD module in mainline backend | Good candidate |
| `velocity/api/sentinel.py` | overlaps with `backend/routers/sentinel.py` but focuses on consent/GDPR/biometric storage | Selective candidate |
| `velocity/api/catalyst.py` | overlaps with `backend/api/routes_catalyst.py` | Merge conflict likely |
| `velocity/api/ws.py` | overlaps conceptually with current websocket/event logic | Selective candidate |
| `velocity/api/analytics.py` | weak/no exact current equivalent | Good candidate |
| `velocity/api/persona.py` | likely additive | Good candidate |
| `velocity/api/kanban.py` | no clear current equivalent in mainline | Good candidate |
| `velocity/services/comfyui_service.py` | conflicts with current ingress + Comfy routing + live GPU architecture | Poor direct candidate |
| `velocity/main.py` | conflicts with `backend/main.py` | Do not merge directly |
| `velocity/main.go` + `internal/*` | alternate runtime architecture | Do not merge directly |
| `VelocityApp/*` | overlaps with current iOS app | Selective candidate only |

---

## Scored Intake Table

| Sourik Path / Scope | Score | Merge Recommendation | Reason |
| --- | ---: | --- | --- |
| `Sourik/velocity/api/leads.py` | 8 | Selective merge candidate | Real CRUD, qualification, demographics endpoints. Mainline has product need here and no equally complete direct equivalent. Needs DB contract alignment. |
| `Sourik/velocity/api/kanban.py` | 8 | Selective merge candidate | Kanban behavior is useful and currently underrepresented in mainline implementation. |
| `Sourik/velocity/api/analytics.py` | 8 | Selective merge candidate | Adds reporting/analytics surface that appears useful for Marketing and Oracle support. |
| `Sourik/velocity/api/persona.py` | 7 | Selective merge candidate | Likely additive business logic and API value. |
| `Sourik/velocity/api/chat_logs.py` | 7 | Selective merge candidate | Useful if mapped into Oracle / CRM flows; needs contract alignment with current auth and DB. |
| `Sourik/velocity/api/ws.py` | 7 | Selective merge candidate | Useful patterns and tests likely exist, but websocket ownership already exists in current backend. |
| `Sourik/velocity/api/sentinel.py` | 7 | Extract specific features only | Valuable for biometric consent, GDPR, and export patterns. But it is SQLite-centered and overlaps with current Sentinel runtime. |
| `Sourik/velocity/tests/api/*` | 9 | Strong import candidate | Test suites are high-value, especially for a fragile future merge. Adapt tests even if code is not merged verbatim. |
| `Sourik/velocity/tests/internal/nemoclaw/*` | 7 | Import selectively | Good coverage and behavioral protection if Go/Nemo concepts are retained anywhere. |
| `Sourik/velocity/services/ad_network_skills.py` | 7 | Selective merge candidate | Likely useful for Catalyst ad automation and may complement current Meta-focused path. |
| `Sourik/velocity/services/social_posting.py` | 7 | Selective merge candidate | Useful capability if social publishing remains in scope. |
| `Sourik/velocity/services/catalyst_content.py` | 7 | Selective merge candidate | Useful Catalyst logic, but must be aligned with current Comfy and asset pipeline. |
| `Sourik/velocity/services/comfyui_service.py` | 4 | Reference only, do not merge directly | Hardcodes stale host/IP and assumes a different Comfy deployment pattern from the current live ingress-managed GPU model. |
| `Sourik/velocity/frontend/src/app/marketing/page.tsx` | 7 | Selective UI import candidate | Useful product surface not currently dominant in mainline app. Needs design-system integration and router alignment. |
| `Sourik/velocity/frontend/src/components/marketing/*` | 7 | Selective UI import candidate | Likely useful for Catalyst/marketing module. |
| `Sourik/velocity/frontend/src/components/dashboard/*` | 6 | Compare component by component | Useful ideas, but mainline already has strong dashboard surfaces. Merge only where functionality is genuinely additive. |
| `Sourik/velocity/frontend/src/lib/api.ts` | 5 | Reference only; do not merge as-is | Useful contract hints, but current mainline already has API client layers. This should inform consolidation, not become a second truth. |
| `Sourik/VelocityApp/Features/CameraView.swift` | 7 | Selective import candidate | Good feature spike: camera capture + send-to-Comfy flow + time/light controls. Worth comparing to current iOS inventory/AR path. |
| `Sourik/VelocityApp/Features/TimeControlSlider.swift` | 7 | Selective import candidate | Likely useful to augment Sun/lighting feature work. |
| `Sourik/VelocityApp/Features/TimeLightEngine.swift` | 7 | Selective import candidate | Strong fit with current Velocity iOS sun-path direction. |
| `Sourik/VelocityApp/Core/Router.swift` | 5 | Review only | Could help, but current iOS structure already has navigation patterns. |
| `Sourik/velocity/main.py` | 3 | Do not merge directly | It creates a second FastAPI root with a different DB model, routing shape, and operational assumptions. Extract modules only. |
| `Sourik/velocity/main.go` | 3 | Do not merge directly | Alternate runtime center. Valuable as concept or archived subsystem, but not compatible with current mainline architecture without a deliberate platform decision. |
| `Sourik/velocity/internal/nemoclaw/*` | 4 | Review as architecture experiments only | Significant conceptual overlap with current Python Nemoclaw path. A direct merge would create two control centers. |
| `Sourik/velocity/internal/mcp/*` | 5 | Review selectively | Interesting if you want future MCP work, but not aligned with current operational center yet. |
| `Sourik/velocity/internal/oracle/*` | 4 | Reference only for now | Current mainline already has an Oracle implementation direction in Python. Direct merge would fork the architecture. |
| `Sourik/velocity/internal/sentinel/sentinel_api.go` | 4 | Reference only | Sentinel is already active in Python backend. |
| `Sourik/velocity/integrations/*.go` | 5 | Review case-by-case | Potentially useful adapters, but only if the Go runtime is retained. |
| `Sourik/velocity/docs/COMFYUI_HANDOFF.md` | 6 | Keep as reference | Useful context for intended wire-up, but assumes VPN/headscale-era setup that no longer matches current ingress truth. |
| `Sourik/SPRINT_SUMMARY_FOR_SAGNIK.md` | 7 | Keep as reference artifact | Useful for intent, coverage claims, and blocked wire list. Not production code. |
| `Sourik/SPEC.md` | 5 | Archive as historical spec | Useful context, but contains stale node IPs, port assumptions, and stage-only instructions that no longer match live infrastructure. |
| `Sourik/PRD.md` | 2 | Archive only | Too thin to be operationally meaningful. |
| `Sourik/velocity/README.md` | 6 | Keep as architecture snapshot | Good summary of Sourik’s intended architecture. |
| `Sourik/velocity/.env` | 1 | Banish | Local secrets/config residue. Must not merge. |
| `Sourik/desineuron-l4-node.pem` | 1 | Banish | Private key material in source tree. Never merge. |
| `Sourik/velocity/db/prototype.db` | 1 | Banish | Local prototype database, not source. |
| `Sourik/velocity/prototype.db` | 1 | Banish | Same issue. |
| `Sourik/velocity/.coverage` | 1 | Banish | Coverage artifact. |
| `Sourik/velocity/coverage*` | 1 | Banish | Coverage outputs, not source. |
| `Sourik/velocity/.agent/*coverage*`, `*test_output*` | 1 | Banish | CI/test residue. |
| `Sourik/velocity/antigravity_server` | 1 | Banish | Compiled binary, not source. |
| `Sourik/velocity/antigravity_test_build.exe` | 1 | Banish | Compiled Windows artifact, not source. |
| `Sourik/velocity/__pycache__`, `.pytest_cache` | 1 | Banish | Generated caches. |
| `Sourik/velocity/logs/VALIDATION_FINAL.log` | 2 | Archive only | Useful as evidence, not source. |
| `Sourik/velocity/test_out.txt`, `guide_extracted.txt`, `guide_utf8.txt` | 2 | Archive only | Scratch outputs. |
| `Sourik/velocity/stubs/*` | 3 | Archive or keep in a clearly marked scratch area | Potentially useful examples, but not merge targets. |
| `Sourik/velocity/archive/*` | 2 | Archive only | Historical material. |

---

## Bloat and Residue in Sourik

These are immediate no-merge items:

- private keys
- `.env`
- `.coverage`
- `coverage*`
- `.pytest_cache`
- `__pycache__`
- compiled binaries
- local sqlite databases
- raw logs
- scratch text files

These do not need debate. They are not source code.

---

## Redundant vs Additive Features

### Redundant or Architecturally Conflicting

1. **FastAPI root app**
   - `Sourik/velocity/main.py`
   - conflicts with current `backend/main.py`
   - creates a second root service with different routing and DB assumptions

2. **Go agent runtime**
   - `Sourik/velocity/main.go`
   - `internal/nemoclaw/*`
   - `internal/mcp/*`
   - this is an alternate operational center, not a drop-in feature set

3. **ComfyUI service**
   - assumes stale IP-based deployment
   - current system already has:
     - stable ingress
     - GPU worker tagging
     - auto-healing route sync
     - Linux AWS control plane

### Additive and Potentially Valuable

1. **Lead / Kanban / Persona / Analytics Python APIs**
   - mainline can benefit directly from these

2. **Sentinel consent and GDPR patterns**
   - these are useful as selective feature imports into current Sentinel

3. **Marketing frontend**
   - a real additive surface for the Catalyst/marketing module

4. **iOS camera and time/light features**
   - fit directly with current iPad vision and sun/AR direction

5. **Test suites**
   - very high value regardless of whether code merges directly

---

## Compatibility with Built Features

### Works with Current Mainline Direction

- property and lead workflows
- marketing/campaign intelligence
- camera-driven iOS interactions
- GDPR/consent handling
- Kanban CRM motions

### Conflicts with Current Mainline Truth

- SQLite/prototype-first database assumptions
- hardcoded or stale infrastructure endpoints
- alternate Go-first NemoClaw/MCP control center
- separate backend root service
- stale VPN/headscale-era deployment assumptions

---

## Recommended Intake Strategy

### Merge Now Candidates

- `velocity/api/leads.py`
- `velocity/api/kanban.py`
- `velocity/api/analytics.py`
- `velocity/api/persona.py`
- tests supporting the above
- selected marketing frontend components
- selected iOS camera/time-light feature files

### Extract, Rewrite, Then Merge

- `velocity/api/sentinel.py`
- `velocity/api/chat_logs.py`
- `velocity/services/*`
- `frontend/src/lib/api.ts`

### Do Not Merge Directly

- `velocity/main.py`
- `velocity/main.go`
- `velocity/internal/nemoclaw/*`
- `velocity/internal/oracle/*`
- `velocity/internal/mcp/*`
- `velocity/services/comfyui_service.py`

### Banish Immediately from Merge Candidate Set

- `.env`
- `.pem`
- `.db`
- `coverage*`
- `.coverage`
- `.pytest_cache`
- `__pycache__`
- binaries
- logs
- scratch outputs

---

## Final Recommendation

Sourik’s code should be treated as:

- **30% importable feature work**
- **30% useful reference and test material**
- **40% architectural conflict or residue**

The best path is:

1. strip all residue first
2. import Python feature modules selectively
3. import tests aggressively
4. compare marketing frontend additions against current app
5. compare iOS camera/time-light features against current iOS app
6. keep the Go/Nemo/MCP stack out of the first merge unless you deliberately choose to adopt that architecture

That will give you the value in Sourik’s work without poisoning the current mainline with a second operating model.