Note (2026-04-24): After this document was written, legal_entity was renamed to tenant and the old tenant was renamed to organization. Read references to these terms with the pre-rename meaning.

Documents Module Split — Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Split documents.clj and document_management.clj into a com.getorcha.erp.http.documents.* namespace tree with grouped handlers, unified URLs, and deduplicated shared code.

Architecture: Pure refactoring with one behavior change (add list SSE to management). Create ~12 new namespace files, wire routes through parent assembler, update all external references, redistribute tests, delete old files.

Tech Stack: Clojure, Reitit routing, HTMX/Hiccup, HoneySQL, core.async (SSE)

Design doc: docs/plans/2026-02-25-documents-module-split-design.md

Reference: Route Name Mapping

Old route names → new route names. Every external reference must be updated.

Reference: External Files That Reference Old Route Names

These files (outside the two being split) reference old route names and need updating:

Reference: File Path Layout

src/com/getorcha/erp/http/
├── documents.clj                          (REWRITE: route assembly + by-hash + 404)
├── documents/
│   ├── shared.clj                         (NEW)
│   ├── upload.clj                         (NEW)
│   ├── accounts_payable.clj               (NEW)
│   ├── management.clj                     (NEW)
│   └── view.clj                           (NEW: route assembly + get-document dispatch)
│   └── view/
│       ├── shared.clj                     (NEW)
│       ├── invoice.clj                    (NEW)
│       ├── notice.clj                     (NEW)
│       ├── contract.clj                   (NEW)
│       ├── purchase_order.clj             (NEW)
│       └── goods_received_note.clj        (NEW)
├── document_management.clj                (DELETE)

test/com/getorcha/erp/http/
├── documents_test.clj                     (REWRITE: route assembly tests only)
├── documents/
│   ├── upload_test.clj                    (NEW)
│   ├── accounts_payable_test.clj          (NEW)
│   ├── management_test.clj               (NEW)
│   └── view_test.clj                     (NEW)
│   └── view/
│       ├── invoice_test.clj               (NEW)
│       └── contract_test.clj              (NEW)
├── document_management_test.clj           (DELETE)

Phase 1: Create New Namespaces

During this phase, old files remain untouched and functional. New namespaces are created but not route-wired. Verify each compiles in the REPL.

Task 1: Create documents.shared

Files:

• Create: src/com/getorcha/erp/http/documents/shared.clj

What moves here (from documents.clj unless noted):

New functions to create:

make-list-events-handler — parameterized list SSE factory:

(defn make-list-events-handler
  "Creates a list-events SSE handler. Takes:
   - `type-filter` — set of document type keywords to include (nil = all)
   - `row-renderer` — fn of [router opts document] → hiccup row"
  [type-filter row-renderer]
  (fn [{:keys [db-pool identity document-events ::reitit/router] :as request}
       respond _raise]
    ;; Same pub/sub pattern as current list-events in documents.clj (lines 2389-2474)
    ;; but with type-filter check: skip events where doc type not in filter set
    ;; and delegate row rendering to row-renderer
    ...))

Step 1: Create the file with all shared functions. Make all functions public (they're cross-namespace now).

Step 2: Verify it compiles:

(require 'com.getorcha.erp.http.documents.shared :reload)

Step 3: Commit:

git add src/com/getorcha/erp/http/documents/shared.clj
git commit -m "refactor(documents): create shared namespace with deduplicated helpers"

Task 2: Create documents.upload

Files:

• Create: src/com/getorcha/erp/http/documents/upload.clj

What moves here:

The upload handler from documents.clj:1723-1778. This is the single unified upload handler.

Key change: the HX-Redirect on single file upload should point to the new unified detail route ::view/detail instead of ::detail. Since the upload namespace can't reference the view namespace's route name at compile time (circular), use path-for with the fully qualified keyword :com.getorcha.erp.http.documents.view/detail.

(defn routes [_config]
  ["/upload"
   {:name ::upload
    :post {:summary    "Upload document(s)"
           :parameters {:multipart [:map-of :keyword :any]}
           :handler    #'upload}}])

Step 1: Create the file. Require documents.shared for legal-entity-ids, excel-content-type?.

Step 2: Verify it compiles.

Step 3: Commit:

git add src/com/getorcha/erp/http/documents/upload.clj
git commit -m "refactor(documents): create upload namespace with unified handler"

Task 3: Create view type-specific modules

Files:

• Create: src/com/getorcha/erp/http/documents/view/invoice.clj
• Create: src/com/getorcha/erp/http/documents/view/notice.clj
• Create: src/com/getorcha/erp/http/documents/view/contract.clj
• Create: src/com/getorcha/erp/http/documents/view/purchase_order.clj
• Create: src/com/getorcha/erp/http/documents/view/goods_received_note.clj

view.invoice — from documents.clj:

This module also defines its own sub-routes (mounted under the view routes):

(defn routes [_config]
  [""
   ["/export/datev"
    {:name ::export-datev
     :post {:handler #'export-datev}}]
   ["/export/datev/status"
    {:name ::datev-export-status
     :get  {:handler #'datev-export-status}}]
   ["/add-to-qa-dataset"
    {:name ::add-to-qa-dataset
     :post {:handler #'add-to-qa-dataset}}]])

Public functions needed by other modules:

• invoice-detail-view — called by view dispatcher
• datev-export-section — called by detail SSE on :export events

view.notice — from documents.clj:

Public: notice-detail-view

No routes — purely a rendering module.

view.contract — from document_management.clj:

Public: contract-detail-view

No routes.

view.purchase-order — from document_management.clj:

Public: po-detail-view

No routes.

view.goods-received-note — from document_management.clj:

Public: grn-detail-view

No routes.

Step 1: Create all five files.

Step 2: Verify each compiles.

Step 3: Commit:

git add src/com/getorcha/erp/http/documents/view/
git commit -m "refactor(documents): create type-specific detail view modules"

Task 4: Create documents.view.shared

Files:

• Create: src/com/getorcha/erp/http/documents/view/shared.clj

What moves here:

Key design for the merged detail-page-content: dispatch rendering by doc type:

(case (some-> (:document/type document) name)
  "invoice"            (view.invoice/invoice-detail-view ...)
  "financial-notice"   (view.notice/notice-detail-view ...)
  "contract"           (view.contract/contract-detail-view ...)
  "purchase-order"     (view.purchase-order/po-detail-view ...)
  "goods-received-note" (view.goods-received-note/grn-detail-view ...)
  ;; default/unknown: show raw structured data or placeholder
  nil)

Key design for merged detail-events: remove the cross-type redirect. On terminal ingestion, just re-render detail-area-content with the document. On :export events, delegate to view.invoice/datev-export-section.

Key design for merged reingest: use the documents.clj version which returns rendered detail-area-content HTML (stays on page with SSE progress). The DM version just does HX-Redirect which is inferior UX.

Step 1: Create the file.

Step 2: Verify it compiles.

Step 3: Commit:

git add src/com/getorcha/erp/http/documents/view/shared.clj
git commit -m "refactor(documents): create shared detail view with unified SSE and dispatch"

Task 5: Create documents.view

Files:

• Create: src/com/getorcha/erp/http/documents/view.clj

What moves here:

The get-document handler — merged from documents.clj:1596-1703 and document_management.clj:1155-1224. This is the dispatcher that loads the document and delegates to the type-specific view via view.shared/detail-page.

Also: get-document-by-hash from documents.clj:1706-1720 — stays here since it's a document-level lookup, not type-specific. Actually, per the design this goes to the parent. Move it there in Task 7.

Route assembly:

(defn routes [_config]
  ["/view/:document-id"
   [""
    {:name ::detail
     :get  {:summary    "Document detail view"
            :parameters {:path {:document-id :uuid}}
            :handler    #'get-document}}]
   ["/events"
    {:name ::detail-events
     :get  {:summary    "SSE events for document detail"
            :parameters {:path {:document-id :uuid}}
            :handler    #'view.shared/detail-events}}]
   ["/reingest"
    {:name ::reingest
     :post {:summary    "Re-ingest document"
            :parameters {:path {:document-id :uuid}}
            :handler    #'view.shared/reingest}}]
   (view.invoice/routes _config)])

Step 1: Create the file.

Step 2: Verify it compiles.

Step 3: Commit:

git add src/com/getorcha/erp/http/documents/view.clj
git commit -m "refactor(documents): create view namespace with route assembly and type dispatch"

Task 6: Create documents.accounts-payable

Files:

• Create: src/com/getorcha/erp/http/documents/accounts_payable.clj

What moves here (all from documents.clj):

List events: either move list-events directly (it has AP-specific logic like bulk selection rendering and DATEV status) or call shared/make-list-events-handler with AP config. Given the AP list-events has bulk selection and DATEV-specific logic interleaved, it's cleaner to keep it as a direct handler here rather than trying to parameterize all that.

Route definition:

(defn routes [_config]
  ["/accounts-payable"
   [""
    {:name ::list
     :get  {:summary    "List AP documents"
            :parameters {:query [...]}
            :handler    #'list-documents}}]
   ["/events"
    {:name ::list-events
     :get  {:summary "SSE events for AP list"
            :handler #'list-events}}]
   ["/search"
    {:name ::search
     :get  {:summary    "Search AP documents"
            :parameters {:query [:map [:q {:optional true} :string]]}
            :handler    #'search-documents}}]
   ["/bulk"
    ["/toggle/:document-id"
     {:name ::bulk-toggle
      :post {:summary    "Toggle document selection"
             :parameters {:path {:document-id :uuid}}
             :handler    #'bulk-toggle}}]
    ["/toggle-all"
     {:name ::bulk-toggle-all
      :post {:handler #'bulk-toggle-all}}]
    ["/deselect-all"
     {:name ::bulk-deselect-all
      :post {:handler #'bulk-deselect-all}}]
    ["/export-datev"
     {:name ::bulk-export-datev
      :post {:handler #'bulk-export-datev}}]]])

Important: Update all internal path-for calls to use new route names. For example, document-row generates links to ::detail which must become :com.getorcha.erp.http.documents.view/detail.

Step 1: Create the file.

Step 2: Verify it compiles.

Step 3: Commit:

git add src/com/getorcha/erp/http/documents/accounts_payable.clj
git commit -m "refactor(documents): create accounts-payable namespace with list, bulk, and SSE"

Task 7: Create documents.management

Files:

• Create: src/com/getorcha/erp/http/documents/management.clj

What moves here (all from document_management.clj):

New: Add list-events SSE handler. Use shared/make-list-events-handler with management's type filter and row renderer:

(def ^:private list-events
  (shared/make-list-events-handler
   managed-types   ;; #{:contract :purchase-order :goods-received-note :other}
   document-row))  ;; management's row renderer

If the parameterized approach is too awkward due to management-specific query/rendering needs, write a dedicated handler modeled on the AP one but filtering to management types.

Route definition:

(defn routes [_config]
  ["/management"
   [""
    {:name ::list
     :get  {:summary    "List managed documents"
            :parameters {:query [...]}
            :handler    #'list-documents}}]
   ["/events"
    {:name ::list-events
     :get  {:summary "SSE events for management list"
            :handler #'list-events}}]
   ["/search"
    {:name ::search
     :get  {:summary    "Search managed documents"
            :parameters {:query [:map [:q {:optional true} :string]]}
            :handler    #'search-documents}}]])

Important: Same as AP — update all path-for calls to use new route names. Detail links in document-row → :com.getorcha.erp.http.documents.view/detail.

Step 1: Create the file.

Step 2: Verify it compiles.

Step 3: Commit:

git add src/com/getorcha/erp/http/documents/management.clj
git commit -m "refactor(documents): create management namespace with list, search, and SSE"

Phase 2: Wire Routes and Switch Over

Task 8: Rewrite documents.clj as route assembler

Files:

• Modify: src/com/getorcha/erp/http/documents.clj

Rewrite the file entirely. It becomes a thin route assembler (~30 lines):

(ns com.getorcha.erp.http.documents
  "Document routes — assembles all document sub-module routes."
  (:require [com.getorcha.erp.http.documents.accounts-payable :as accounts-payable]
            [com.getorcha.erp.http.documents.management :as management]
            [com.getorcha.erp.http.documents.shared :as shared]
            [com.getorcha.erp.http.documents.upload :as upload]
            [com.getorcha.erp.http.documents.view :as view]
            [com.getorcha.db.sql :as db.sql]
            [ring.util.http-response :as ring.resp]))


(defn ^:private get-document-by-hash
  "Get document by content hash."
  [{:keys [db-pool parameters] :as request} respond _raise]
  (let [hash     (get-in parameters [:path :document-hash])
        document (db.sql/execute-one!
                  db-pool
                  {:select [:*]
                   :from   [:document]
                   :where  [:and
                            [:= :content-hash hash]
                            [:in :legal-entity-id (shared/legal-entity-ids request)]]}
                  {:builder-fn shared/document-builder-fn})]
    (if document
      (respond (ring.resp/ok document))
      (respond (ring.resp/not-found {:error "Document not found"})))))


(defn routes [_config]
  ["/documents"
   ["" {:get {:handler (fn [_ respond _] (respond (ring.resp/not-found "")))}}]
   ["/by-hash/:document-hash"
    {:name ::by-hash
     :get  {:summary    "Get document by content hash"
            :parameters {:path {:document-hash :string}}
            :handler    #'get-document-by-hash}}]
   (upload/routes _config)
   (accounts-payable/routes _config)
   (management/routes _config)
   (view/routes _config)])

Step 1: Rewrite the file.

Step 2: Verify it compiles.

Step 3: Do NOT commit yet — tests will fail until external references are updated.

Task 9: Update external references

Files:

• Modify: src/com/getorcha/erp/http.clj — remove document-management require, keep single documents require
• Modify: src/com/getorcha/erp/ui/layout.clj:39-40 — update sidebar nav route names
• Modify: src/com/getorcha/erp/http/profile.clj:33 — update redirect route name
• Modify: src/com/getorcha/erp/http/login.clj:242,313,394 — update post-login redirect route names
• Delete: src/com/getorcha/erp/http/document_management.clj

erp/http.clj changes:

• Remove require: [com.getorcha.erp.http.document-management :as erp.http.document-management]
• Remove line 50: (erp.http.document-management/routes config)
• Line 49 stays: (erp.http.documents/routes config) (now assembles everything)

erp/ui/layout.clj changes (lines 39-40):

;; Old:
(erp.http.routes/path-for router :com.getorcha.erp.http.documents/list)
(erp.http.routes/path-for router :com.getorcha.erp.http.document-management/list)
;; New:
(erp.http.routes/path-for router :com.getorcha.erp.http.documents.accounts-payable/list)
(erp.http.routes/path-for router :com.getorcha.erp.http.documents.management/list)

erp/http/profile.clj change (line 33):

;; Old:
(erp.http.routes/path-for router :com.getorcha.erp.http.documents/list)
;; New:
(erp.http.routes/path-for router :com.getorcha.erp.http.documents.accounts-payable/list)

erp/http/login.clj changes (lines 242, 313, 394):

;; Old (all 3 occurrences):
(erp.http.routes/path-for router :com.getorcha.erp.http.documents/list)
;; New:
(erp.http.routes/path-for router :com.getorcha.erp.http.documents.accounts-payable/list)

Also update the require alias in login.clj if it uses ::erp.http.documents/list shorthand — it does on line 242. Either switch to fully qualified keyword or update the alias.

Step 1: Make all changes.

Step 2: Delete document_management.clj.

Step 3: Verify all source files compile:

(require 'com.getorcha.erp.http :reload-all)

Step 4: Commit:

git add src/com/getorcha/erp/http.clj \
        src/com/getorcha/erp/http/documents.clj \
        src/com/getorcha/erp/ui/layout.clj \
        src/com/getorcha/erp/http/profile.clj \
        src/com/getorcha/erp/http/login.clj
git rm src/com/getorcha/erp/http/document_management.clj
git commit -m "refactor(documents): wire new route structure, remove old document-management"

Phase 3: Redistribute Tests

Task 10: Create test files for new namespaces

Files:

• Create: test/com/getorcha/erp/http/documents/upload_test.clj
• Create: test/com/getorcha/erp/http/documents/accounts_payable_test.clj
• Create: test/com/getorcha/erp/http/documents/management_test.clj
• Create: test/com/getorcha/erp/http/documents/view_test.clj
• Create: test/com/getorcha/erp/http/documents/view/invoice_test.clj

Redistribute from existing tests. Route name references must be updated throughout.

upload_test.clj — from documents_test.clj:

• upload-document-test (lines 45-123) — update route refs from ::http.documents/upload to ::http.upload/upload, ::http.documents/by-hash to ::http.documents/by-hash

accounts_payable_test.clj — from documents_test.clj:

• list-documents-test (lines 126-144) — update ::http.documents/list → ::http.ap/list
• bulk-toggle-test (lines 604-671) — update all ::http.documents/bulk-* → ::http.ap/bulk-*
• bulk-toggle-all-test (lines 674-721) — same
• bulk-export-datev-test (lines 724-741) — same
• List SSE tests from list-sse-sends-event-on-status-transition-test (lines 418-468) — update route refs

view_test.clj — from both test files:

• get-document-test (docs_test:147-190) — update ::http.documents/detail → ::http.view/detail
• sse-events-test (docs_test:193-236) — split: list SSE tests go to AP, detail SSE tests stay here
• detail-sse-sends-event-on-status-change-test (docs_test:292-342) — update refs
• display-file-path-test (docs_test:345-415) — update refs
• tenant-isolation-test (docs_test:471-545) — update refs
• detail-document-test (dm_test:134-156) — merge into view tests
• detail-sse-test (dm_test:200-236) — merge into view tests
• navigation-preserves-filters-test (dm_test:242-256) — update path

management_test.clj — from document_management_test.clj:

• list-documents-test (dm_test:88-128) — update ::http.dm/list → ::http.management/list
• search-documents-test (dm_test:285-292) — update path

view/invoice_test.clj — if any DATEV export tests exist in documents_test, move them here. Currently none exist as standalone tests, but display-file-path-test touches DATEV. Keep it in view_test.clj for now.

Shared test helpers (temp-file, purge-queue!, read-sse-events, update-ingestion-status!, mark-ingestion-completed!) — put in a shared test helper namespace or duplicate in each test file that needs them. Prefer a shared test helper:

• Create: test/com/getorcha/erp/http/documents/test_helpers.clj for shared test utilities

Step 1: Create all test files with redistributed tests and updated route references.

Step 2: Run tests:

clj -X:test:silent :nses '[com.getorcha.erp.http.documents.upload-test
                            com.getorcha.erp.http.documents.accounts-payable-test
                            com.getorcha.erp.http.documents.management-test
                            com.getorcha.erp.http.documents.view-test]'

Step 3: Fix any failures.

Step 4: Delete old test files:

git rm test/com/getorcha/erp/http/documents_test.clj
git rm test/com/getorcha/erp/http/document_management_test.clj

Step 5: Commit:

git add test/com/getorcha/erp/http/documents/
git rm test/com/getorcha/erp/http/documents_test.clj
git rm test/com/getorcha/erp/http/document_management_test.clj
git commit -m "refactor(documents): redistribute tests to match new namespace structure"

Phase 4: Verify and Clean Up

Task 11: Run full test suite

Step 1: Run all tests:

clj -X:test:silent 2>&1 | grep -A 5 -E "(FAIL in|ERROR in|Execution error|failed because|Ran .* tests)"

Step 2: Fix any failures. Common issues:

• Missed route name references (grep for old names)
• Missing requires in new namespaces
• path-for calls using old route names in Hiccup templates

Step 3: Grep for any remaining old references:

# Should return zero results
grep -r "erp.http.document-management" src/ test/
grep -r "erp.http.documents/" src/ test/ | grep -v "erp.http.documents\." | grep -v documents.clj

Step 4: Commit any fixes:

git commit -m "fix(documents): resolve remaining references after module split"

Task 12: Verify UI manually

Step 1: Start the system: (reset) in REPL.

Step 2: Verify in browser:

• /documents → 404
• /documents/accounts-payable → AP list page loads
• /documents/management → DM list page loads
• Click a document → /documents/view/:uuid loads correct detail view
• Upload a file → redirects to /documents/view/:uuid
• Navigation arrows work on detail page
• SSE updates work on list pages (upload a file, see it appear)
• SSE updates work on detail page (reingest, see status change)
• Bulk selection works on AP page
• Search works on both list pages
• Sidebar navigation links work

Step 3: Fix any issues found.

Step 4: Final commit if needed.