feat: Complete code integration of modules (#18)

The complete code integration is done.

Co-authored-by: Sagnik <sagnik7896@gmail.com>
Reviewed-on: #18

.Agent Context/Issues/2026-04-12-sourik-root-integration-closure.md

@@ -0,0 +1,135 @@
+# Sourik Root Integration Closure
+
+## Summary
+
+This issue tracks the root-side integration of the useful Sourik subsystems into the current Project Velocity mainline without replacing the root FastAPI shell, root Sentinel ownership, or the existing Python-native Oracle v1 surface.
+
+The objective was to absorb the missing operational pieces into the root codebase so Sprint 1 truth is judged by current product reality rather than by stale planning artifacts.
+
+## Scope Closed In This Pass
+
+### CRM backend and sync
+
+- landed canonical root CRM routes for:
+  - `GET/POST/PUT/DELETE /api/leads`
+  - `GET /api/leads/{lead_id}`
+  - `GET /api/leads/demographics`
+  - `GET/POST /api/chat-logs`
+  - `GET /api/kanban/board`
+  - `PUT /api/kanban/move`
+  - `POST /api/leads/seed-synthetic`
+- added dedicated CRM websocket stream at `GET /ws/crm`
+- added root-side CRM event broadcasting for:
+  - lead create
+  - lead update
+  - lead delete
+  - kanban move
+  - chat log create
+  - synthetic seed runs
+  - Oracle writebacks
+
+### Oracle append and writeback contract
+
+- kept root Oracle v1 as the primary public Oracle surface
+- appended persona and workflow orchestration under the existing Oracle v1 flow
+- added real MCP execution endpoint:
+  - `POST /api/oracle/mcp/execute`
+- added Oracle action ledger and read/writeback routes:
+  - `GET /api/oracle/actions`
+  - `GET /api/oracle/actions/{action_id}`
+  - `POST /api/oracle/actions/writeback`
+- Oracle prompt submissions now create persisted action records tied to execution output
+- Oracle writebacks now support canonical lead updates for:
+  - score adjustments
+  - stage changes
+  - qualification changes
+  - metadata patching
+  - note append
+  - Oracle-generated message insertion into `chat_logs`
+
+### MCP and search
+
+- converted the MCP registry from a placeholder slot into an executable root service
+- external search now executes against:
+  - Brave Search if `BRAVE_API_KEY` is configured
+  - DuckDuckGo fallback otherwise
+- CRM and local property retrieval tools now execute against the root CRM schema through the root DB pool
+
+### Catalyst marketing backend parity
+
+- replaced hardcoded campaign summaries with unified ad-network service backed by root code
+- added root Meta plus Google Ads unified campaign listing
+- added unified insights endpoint with platform filtering
+- added budget update route for Meta plus Google
+- added bid strategy update route for Meta plus Google
+- added Google-aware campaign creation path so Catalyst campaign creation is no longer Meta-only
+
+Routes covered in this pass:
+
+- `GET /api/catalyst/campaigns`
+- `POST /api/catalyst/campaigns/create`
+- `GET /api/catalyst/insights/realtime`
+- `PUT /api/catalyst/budget`
+- `PUT /api/catalyst/bid-strategy`
+
+### Frontend carry-forward
+
+- preserved the existing root Catalyst shell
+- kept the vertically stacked `Marketing` sub-tab inside Catalyst
+- no second marketing app or second frontend API source of truth was introduced
+
+## Files Added Or Materially Updated
+
+### Backend
+
+- `backend/services/ad_network_service.py`
+- `backend/services/mcp_registry.py`
+- `backend/api/routes_catalyst.py`
+- `backend/api/routes_crm.py`
+- `backend/api/routes_oracle.py`
+- `backend/oracle/action_service.py`
+- `backend/oracle/router_v1.py`
+- `backend/main.py`
+
+### Tests
+
+- `backend/tests/test_catalyst_routes.py`
+- `backend/tests/test_oracle_routes.py`
+- `backend/tests/test_crm_websocket.py`
+
+## Verification Completed
+
+- `python -m pytest Project_Velocity/backend/tests/test_catalyst_routes.py Project_Velocity/backend/tests/test_oracle_routes.py Project_Velocity/backend/tests/test_crm_websocket.py Project_Velocity/backend/tests/test_crm_routes.py Project_Velocity/backend/tests/oracle/test_persona_service.py Project_Velocity/backend/tests/test_nemoclaw_runtime.py`
+- result: `9 passed`
+
+- `npm run build`
+- result: passed
+
+## Production Notes
+
+- Google Ads support is now integrated at the root contract level, but live mutate behavior still depends on valid provider credentials and provider-managed operations.
+- Brave Search becomes the preferred external search provider when `BRAVE_API_KEY` is present; otherwise the root falls back to DuckDuckGo.
+- Oracle writebacks currently target leads as the canonical CRM entity. Additional entity writebacks should follow the same `oracle_actions` ledger rather than introducing side-channel writes.
+
+## Residual Work After This Closure
+
+These are still separate follow-up items, not blockers for closing this integration pass:
+
+- deeper Google Ads mutate coverage beyond provider-managed passthroughs
+- frontend consumption of the CRM websocket stream
+- broader Oracle writebacks beyond `lead`
+- stricter auth and role gating for Oracle action application
+- richer Catalyst campaign creation UX for platform-specific fields
+- prompt inventory and persona-to-runtime mapping docs cleanup
+
+## Acceptance Criteria Met
+
+- root app shell preserved
+- root FastAPI entrypoint preserved
+- root Sentinel ownership preserved
+- no Go runtime adopted
+- no second backend center introduced
+- MCP external search executes for real
+- CRM has a live websocket sync surface
+- Oracle has a persisted action/writeback contract
+- Catalyst backend exposes Google-aware parity routes in the root