{"slug":"business/code-map-appendix","title":"Code Map Appendix","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/code-map-appendix.mdx","bytes":8599,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"Agreed. Add this as the appendix.\n\nAppendix A — Code Map\n\nThis appendix maps the canonical data flow to the main implementation files so engineers can trace behavior in code.\n\n1. Onboarding and tenant schema resolution\n\nColumn 1 Column 2\nResponsibility File / Area\nL0 onboarding flow and tenant activation apps/web/src/components/onboarding/\nTenant schema resolution packages/types/src/adaptive-schema.ts\nTenant runtime configuration tenant_spine_config usage across workflow / onboarding services\n\nWhat to trace\n\n- how department + industry resolve the tenant schema\n- how onboarding completion unlocks workspace readiness\n- how connector setup is tied to tenant context\n\n---\n\n2. Connector auth and sync kickoff\n\nColumn 1 Column 2\nResponsibility File / Area\nConnector auth and sync production services/connector/src/sync-producer.ts\nConnector-specific handlers services/loader/src/handlers/\n\nWhat to trace\n\n- connector installation binding to tenant\n- creamy / needed / delta sync behavior\n- initial queue dispatch after auth success\n\n---\n\n3. Structured data flow (Flow A)\n\nColumn 1 Column 2\nResponsibility File / Area\nStructured ingestion handlers services/loader/src/handlers/hubspot.ts, salesforce.ts, etc.\nCanonical field mapping services/loader/src/pipeline-stages.ts\nPipeline orchestration services/loader/src/pipeline.ts\n8-stage normalization services/normalizer/src/index.ts\nSpine write routing services/spine-v2/src/index.ts\n\nWhat to trace\n\n- raw webhook / poll payload enters loader\n- payload goes through canonical mapping\n- run8StagePipeline() executes\n- normalized entity is routed to the correct Spine table\n- resulting truth becomes available to workspace and cognitive layers\n\n---\n\n4. The 8-stage pipeline\n\nColumn 1 Column 2 Column 3\nStage Meaning Main file\nAnalyze inspect raw payload services/normalizer/src/index.ts\nClassify determine entity / flow services/normalizer/src/index.ts\nFilter tenant/schema filtering services/normalizer/src/index.ts\nRefine normalize field shapes services/normalizer/src/index.ts\nExtract pull canonical entity data services/normalizer/src/index.ts\nValidate schema + required field checks services/normalizer/src/index.ts\nSanity business/data integrity checks services/normalizer/src/index.ts\nSectorize final destination routing services/normalizer/src/index.ts, services/spine-v2/src/index.ts\n\nDeveloper note\nThis is the mandatory path for truth creation. No connector should bypass it.\n\n---\n\n5. Spine / SSOT routing\n\nColumn 1 Column 2\nResponsibility File / Area\nEntity type to table routing services/spine-v2/src/index.ts\nCanonical truth persistence services/spine-v2/src/index.ts\n\nWhat to trace\n\n- ENTITY_TYPE_TO_TABLE\n- destination table resolution\n- structured truth writes\n- prevention of non-canonical write paths\n\n---\n\n6. Unstructured content flow (Flow B)\n\nColumn 1 Column 2\nResponsibility File / Area\nChunking services/knowledge/src/chunking/\nEmbeddings services/knowledge/src/embedding/\nKnowledge ingestion services/knowledge/src/\nEntity linking / metadata projection knowledge + Spine-linked context paths\n\nWhat to trace\n\n- file or content enters ingest\n- text extraction / chunking happens\n- embeddings are created\n- searchable content lands in Knowledge\n- linked metadata / references are attached to Spine entities\n\nRule reminder\nFlow B enriches context and evidence. It does not replace structured truth.\n\n---\n\n7. Entity 360 read model\n\nColumn 1 Column 2\nResponsibility File / Area\nRead-time fusion services/workflow/src/views.ts\nWorkspace transforms services/workflow/src/transformers/\n\nWhat to trace\n\n- Spine truth fetch\n- Knowledge/context fetch\n- signal fetch\n- fusion into a read model for workspace and cognitive use\n\nRule reminder\nEntity 360 is read-only fusion, not a write surface.\n\n---\n\n8. Cognitive loop\n\nColumn 1 Column 2\nResponsibility File / Area\nProposal generation / reasoning services/think/src/\nPolicy and approval rules services/govern/src/\nAction execution services/act/src/\n\nWhat to trace\n\n- Think creates grounded proposals\n- Govern evaluates policy\n- approval token / approval state is enforced\n- Act only runs after approval\n- outcome is returned for re-ingestion\n\n---\n\n9. Flow C (AI sessions, MCP, governed AI memory)\n\nColumn 1 Column 2\nResponsibility File / Area\nMCP ingress services/mcp-connector/src/\nAI reasoning / triage patterns services/think/src/\nGoverned proposal path services/govern/src/, services/act/src/\n\nWhat to trace\n\n- AI session capture\n- proposal creation instead of direct truth write\n- user review / governance path\n- approved action execution\n- result re-enters normal pipeline path\n\nRule reminder\nFlow C never writes directly to Spine truth.\n\n---\n\n10. Approval and action\n\nColumn 1 Column 2\nResponsibility File / Area\nApproval policy enforcement services/govern/src/index.ts, services/govern/src/policies.ts\nAction execution logic services/act/src/index.ts, services/act/src/lib/execution.ts\n\nWhat to trace\n\n- approval requirement checks\n- x-approval-token validation\n- connector execution\n- auditability of action path\n\n---\n\n11. Re-ingestion after action\n\nColumn 1 Column 2\nResponsibility File / Area\nAction result queue-back services/act/src/index.ts\nPipeline re-entry pipeline queue consumers\n\nWhat to trace\n\n- approved action executes externally\n- result is not trusted as final truth immediately\n- result is queued back into pipeline\n- Spine is refreshed through the same canonical path\n\nRule reminder\nTruth must be refreshed through re-ingestion, not assumed from outbound execution alone.\n\n---\n\n12. Quick trace path for developers\n\nUse this sequence when debugging any end-to-end issue:\n\n1. apps/web/... — where the user initiated the action\n2. services/gateway/... — how the request was routed\n3. services/connector/... or services/loader/... — how source data entered\n4. services/normalizer/... — how it was normalized\n5. services/spine-v2/... — where truth was written\n6. services/workflow/... — how it appeared in workspace / Entity 360\n7. services/think/... — how intelligence was generated\n8. services/govern/... — how approval policy was checked\n9. services/act/... — how action executed\n10. queue / pipeline path again — how result re-entered truth\n\n---\n\n13. One-line developer rule\n\nIf you cannot point to the ingest path, the pipeline path, the Spine write path, and the re-ingestion path, the feature is not fully wired.\n\nIf you want, I can also merge this directly into the KT note and produce a final KT v1.0 document in one piece.\n\nThe 12 departments part is correct, but the entity counts in your table do not match the live DOMAIN_SPINE_CONFIG arrays exactly. The schema file confirms the 12 active department configs, but several of the counts shown here are lower than what is currently defined in packages/types/src/schema.ts.\n\nWhat is safe to state canonically\n\nUse this wording instead:\n\n12 Departments Active\n\nTotal: 12 primary runtime department configs are defined in packages/types/src/schema.ts under DOMAIN_SPINE_CONFIG. Each department defines its own:\n\n- entity types — what records are allowed in the Spine path\n- priority fields — what fields the pipeline prioritizes during extraction\n- organic capabilities — what the BFF/UI exposes instead of raw entity types\n- workspace emphasis — what modules and views are emphasized in L1\n- cognitive relevance — what signals and reasoning patterns become meaningful in L2\n\nActive department configs\n\n1. CUSTOMER_SUCCESS\n2. REVOPS\n3. SALES\n4. MARKETING\n5. PRODUCT_ENGINEERING\n6. FINANCE\n7. SERVICE\n8. PROCUREMENT\n9. IT_ADMIN\n10. STUDENT_TEACHER\n11. BIZOPS\n12. PERSONAL\n\nImportant runtime note\n\nDepartment selection is not cosmetic. It determines:\n\n- which entity_types are allowed by schema\n- which fields are prioritized in extraction\n- which organic capabilities appear in the UI\n- which workspace modules are emphasized\n- which signals and reasoning paths become active downstream\n\nAlso add this note\n\nSome tenant-facing department labels resolve into shared base configs through DEPARTMENT_TO_CONFIG_KEY, for example:\n\n- SUPPORT → SERVICE\n- ENGINEERING → PRODUCT_ENGINEERING\n- PRODUCT → PRODUCT_ENGINEERING\n- LEGAL → BIZOPS\n- HR → BIZOPS\n- SUPPLY_CHAIN → PROCUREMENT\n- SERVICE_OPS → SERVICE\n\nBest KT-safe replacement for your last paragraph\n\nEach department has its own schema-driven runtime behavior: allowed entity types, priority fields, organic capability mapping, workspace emphasis, and downstream cognitive relevance. These are defined in packages/types/src/schema.ts through DOMAIN_SPINE_CONFIG, DEPARTMENT_TO_CONFIG_KEY, and ORGANIC_CAPABILITY_MAP.\n"}