{ "format": "pathways-project-bundle", "version": 1, "project": { "id": "mehrlogic-architecture", "engineerIds": [], "roadmap": { "version": 1, "title": "Architecture and workflows", "application": "Mehrlogic · Architecture library", "tasks": [] } }, "engineers": [], "teams": [], "flows": [ { "version": 1, "id": "meeting-copilot-architecture", "name": "Meeting Copilot · System architecture", "projectId": "mehrlogic-architecture", "description": "A native macOS capture helper feeds bounded local meeting context. Only enabled audio, context, and separately enabled screen images reach configured cloud providers.", "notes": [ "Private desktop MVP", "Architecture source reviewed October 14, 2026.", "Desktop source and architecture documentation inspected; physical capture permissions and provider quality were not exercised during this review." ], "presentationNotes": "The sandboxed React window is the control surface. The Electron main process owns the session; Swift captures audio and frames, while Apple Vision reads changed screen text locally. Typed IPC and bounded queues separate these responsibilities.\n\nEnabled audio travels to Azure Speech. Transcript, OCR and opt-in file excerpts become bounded context for Astra. Screen images require a separate explicit setting. Stop cancels work; speech or inference errors can degrade independently.\n\nLocal credentials and optional transcript files stay on the Mac. This assistant offers suggestions to the user; it has no meeting-bot participant, synthesized microphone, or message-sending integration.\n\nReview scope\nDesktop source and architecture documentation inspected; physical capture permissions and provider quality were not exercised during this review.", "diagramType": "architecture", "groups": [ { "id": "mac", "title": "macOS application", "description": "Native capture, isolated UI, local context and optional persistence" }, { "id": "cloud", "title": "Enabled cloud inference", "description": "Separate speech and answer providers; user-controlled data forwarding" } ], "nodes": [ { "id": "ui", "kind": "frontend", "title": "Private assistant UI", "actor": "React · sandboxed Electron", "description": "Start, stop and clear sessions; display transcripts and suggestions through a typed preload bridge. No provider credentials or Node access in the renderer.", "checks": [], "phase": "macOS application", "groupId": "mac" }, { "id": "capture", "kind": "service", "title": "Native capture helper", "actor": "Swift · ScreenCaptureKit", "description": "Capture enabled system audio, optional microphone via AVAudioEngine, and selected display/window frames. Emit independent PCM streams and screen observations to Electron main.", "checks": [], "phase": "macOS application", "groupId": "mac" }, { "id": "context", "kind": "service", "title": "Session and context manager", "actor": "Electron main · bounded queues", "description": "Validate messages, merge transcript/OCR/selected knowledge, coalesce inference, manage cancellation and reconnects. A provider failure does not terminate local capture.", "checks": [], "phase": "macOS application", "groupId": "mac" }, { "id": "ocr", "kind": "service", "title": "Local screen OCR", "actor": "Apple Vision · visual diff", "description": "Recognize changed screen text locally. Selected-screen scope is separate from system-audio capture scope.", "checks": [], "phase": "macOS application", "groupId": "mac" }, { "id": "knowledge", "kind": "database", "title": "Selected local knowledge", "actor": "Opt-in files · lexical index", "description": "Read only the selected folder into an in-memory lexical index; supply relevant excerpts. Remote repositories and embedding services are not implemented connectors.", "checks": [], "phase": "macOS application", "groupId": "mac" }, { "id": "storage", "kind": "database", "title": "Private configuration and transcripts", "actor": "Encrypted settings · optional JSONL", "description": "Keep provider credentials in local encrypted configuration. Optional finalized transcript persistence uses bounded writes; session memory and saved transcripts have separate lifecycles.", "checks": [], "phase": "macOS application", "groupId": "mac" }, { "id": "speech", "kind": "external", "title": "Audio transcription", "actor": "Azure Speech · push PCM", "description": "Transcribe only enabled audio channels. Reconnect individual streams; audio during an outage is discarded rather than silently accumulated.", "checks": [], "phase": "Enabled cloud inference", "groupId": "cloud" }, { "id": "ai", "kind": "external", "title": "Answer and optional vision", "actor": "Astra · OpenAI Responses", "description": "Receive bounded context for structured suggestions with store:false and no action tools. Images are forwarded only when cloud AI and image forwarding are both enabled.", "checks": [], "phase": "Enabled cloud inference", "groupId": "cloud" } ], "edges": [ { "id": "connection-1", "source": "ui", "target": "context", "label": "Typed IPC", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "capture", "target": "context", "label": "Audio / frames", "kind": "next", "direction": "forward" }, { "id": "connection-3", "source": "capture", "target": "ocr", "label": "Changed frames", "kind": "next", "direction": "forward" }, { "id": "connection-4", "source": "ocr", "target": "context", "label": "Screen text", "kind": "next", "direction": "forward" }, { "id": "connection-5", "source": "context", "target": "knowledge", "label": "Relevant excerpts", "kind": "next", "direction": "both" }, { "id": "connection-6", "source": "context", "target": "storage", "label": "Settings / transcript", "kind": "next", "direction": "both" }, { "id": "connection-7", "source": "context", "target": "speech", "label": "Enabled audio", "kind": "next", "direction": "both" }, { "id": "connection-8", "source": "context", "target": "ai", "label": "Context / answers", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "meeting-copilot-workflow", "name": "Meeting Copilot · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Meeting Copilot.", "notes": [ "Private desktop MVP", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "Native capture, local context, and optional cloud assistance meet in a private macOS interface.\n\nStart a session\nEnable the desired capture and cloud routes, then start.\n\nCapture audio and screen\nAudio and changed screen observations are captured independently.\n\nBuild bounded context\nTranscription, local OCR, and relevant knowledge become a bounded context snapshot.\n\nIs a response useful?\nAssess whether a relevant unanswered question has sufficient supporting context.\n\nShow a suggestion\nDisplay a concise suggestion for the user to consider.\n\nContinue listening\nIrrelevant or unsupported questions do not produce an answer.\n\nUser stays in control\nThe user chooses what to say; the app sends no meeting messages.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Start a session", "actor": "User", "description": "Enable the desired capture and cloud routes, then start.", "checks": [], "phase": "Workflow" }, { "id": "capture", "kind": "process", "title": "Capture audio and screen", "actor": "Native helper", "description": "Audio and changed screen observations are captured independently.", "checks": [], "phase": "Workflow" }, { "id": "context", "kind": "process", "title": "Build bounded context", "actor": "Local + enabled providers", "description": "Transcription, local OCR, and relevant knowledge become a bounded context snapshot.", "checks": [], "phase": "Workflow" }, { "id": "assess", "kind": "decision", "title": "Is a response useful?", "actor": "AI assessment", "description": "Assess whether a relevant unanswered question has sufficient supporting context.", "checks": [], "phase": "Workflow" }, { "id": "suggest", "kind": "human", "title": "Show a suggestion", "actor": "Private interface", "description": "Display a concise suggestion for the user to consider.", "checks": [], "phase": "Workflow" }, { "id": "wait", "kind": "end", "title": "Continue listening", "actor": "No suggestion", "description": "Irrelevant or unsupported questions do not produce an answer.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "User stays in control", "actor": "Meeting participant", "description": "The user chooses what to say; the app sends no meeting messages.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "capture", "label": "", "kind": "next" }, { "id": "transition-1", "source": "capture", "target": "context", "label": "", "kind": "next" }, { "id": "transition-2", "source": "context", "target": "assess", "label": "", "kind": "next" }, { "id": "transition-3", "source": "assess", "target": "suggest", "label": "Relevant question", "kind": "branch" }, { "id": "transition-4", "source": "assess", "target": "wait", "label": "No useful answer", "kind": "branch" }, { "id": "transition-5", "source": "suggest", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "lead-finder-architecture", "name": "MehrLogic Lead Finder · System architecture", "projectId": "mehrlogic-architecture", "description": "The Mac Studio coordinator owns outreach records, research, inference and sending. A laptop dashboard connects over authenticated SSH without starting a second processing system.", "notes": [ "In-house macOS product", "Architecture source reviewed October 14, 2026.", "Topology follows coordinator source and the October 12 cutover acceptance record; this review did not connect to the Studio or send messages.", "Optional Gemini, Zoom and measurement integration status was not queried from private runtime settings." ], "presentationNotes": "The documented current installation uses the Studio as a single coordinator and the laptop as a remote dashboard. An authenticated SSH relay reaches a loopback-only API; the dashboard does not start an alternative database, inference worker or sender.\n\nIRS imports, public-website collection, local inference, independent review, outgoing mail and incoming-reply scans have separate durable state. The verified local model is pinned. Search can hand over from Brave to configured Serper after an explicit payment refusal.\n\nSaved sending authority is checked alongside current recipient, evidence, mailbox history and quota state. Uncertain sends stay held until reconciled. Closing or disconnecting the laptop leaves Studio processing intact; a Studio reboot still requires owner login and Keychain access.\n\nReview scope\nTopology follows coordinator source and the October 12 cutover acceptance record; this review did not connect to the Studio or send messages.\nOptional Gemini, Zoom and measurement integration status was not queried from private runtime settings.", "diagramType": "architecture", "groups": [ { "id": "laptop", "title": "Laptop dashboard", "description": "Renderer and managed SSH relay; no local sending fallback" }, { "id": "studio", "title": "Mac Studio coordinator", "description": "Loopback API, durable queues, local inference and encrypted credentials" }, { "id": "external", "title": "Connected services", "description": "Configured search, public evidence, authorized Gmail and optional integrations" } ], "nodes": [ { "id": "ui", "kind": "frontend", "title": "Case board and system health", "actor": "Sandboxed Electron dashboard", "description": "Review cases, authorizations, schedules, demos and processing status. Unknown or stale health is labeled explicitly; closing this dashboard does not stop Studio processing.", "checks": [], "phase": "Laptop dashboard", "groupId": "laptop" }, { "id": "relay", "kind": "infrastructure", "title": "Authenticated dashboard relay", "actor": "SSH · pinned host identity", "description": "Forward the coordinator loopback service and refresh its ephemeral session. Reconnect after network loss; never start laptop SQLite, model inference or email fallback.", "checks": [], "phase": "Laptop dashboard", "groupId": "laptop" }, { "id": "api", "kind": "api", "title": "Coordinator API", "actor": "Electron main · loopback HTTP", "description": "Require the desktop session token, exact Host/Origin and CSRF checks. One coordinator owns current work and emits status/events to the dashboard.", "checks": [], "phase": "Mac Studio coordinator", "groupId": "studio" }, { "id": "discovery", "kind": "service", "title": "Discovery and evidence collection", "actor": "IRS catalog · website workers", "description": "Import public IRS records, find candidate websites and extract supporting passages. Website collection and discovery progress independently from inference and sending.", "checks": [], "phase": "Mac Studio coordinator", "groupId": "studio" }, { "id": "research", "kind": "service", "title": "Research and independent review", "actor": "Durable model queues · Ollama", "description": "Use the verified local gpt-oss:20b model for evidence analysis, drafting and independent review. Optional Gemini transport exists but cloud fallback was disabled at documented cutover.", "checks": [], "phase": "Mac Studio coordinator", "groupId": "studio" }, { "id": "review", "kind": "service", "title": "Authorized sending and replies", "actor": "Gmail checks · adaptive pacing", "description": "Recheck recipient, claims, conversation, authorization and fresh mailbox state. Persist uncertain-send holds and reconcile before another attempt; quota waits do not stop research.", "checks": [], "phase": "Mac Studio coordinator", "groupId": "studio" }, { "id": "store", "kind": "database", "title": "Coordinator workspace", "actor": "SQLite + IRS DB · Keychain vault", "description": "Store cases, queue states, approvals, correspondence, provider holds and encrypted credentials. Application backups preserve durable state; the dashboard has no competing copy.", "checks": [], "phase": "Mac Studio coordinator", "groupId": "studio" }, { "id": "search", "kind": "external", "title": "Search and public websites", "actor": "Brave / Serper · HTTP evidence", "description": "Configured search routing supports durable Brave-to-Serper handover after HTTP 402. Actual provider availability governs progress; website content is evidence rather than authority.", "checks": [], "phase": "Connected services", "groupId": "external" }, { "id": "gmail", "kind": "external", "title": "Authorized Gmail account", "actor": "OAuth · messages and history", "description": "Send only currently authorized messages; read replies and delivery evidence for reconciliation. Mailbox limits and uncertain provider outcomes remain visible durable holds.", "checks": [], "phase": "Connected services", "groupId": "external" }, { "id": "optional", "kind": "external", "title": "Optional integrations", "actor": "Gemini · Zoom · demo metrics", "description": "Separately configured cloud inference, demo scheduling and click/demo measurement. Source support does not imply every integration is enabled.", "checks": [], "phase": "Connected services", "groupId": "external" } ], "edges": [ { "id": "connection-1", "source": "ui", "target": "relay", "label": "Dashboard state", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "relay", "target": "api", "label": "SSH / session", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "api", "target": "store", "label": "Cases / settings", "kind": "next", "direction": "both" }, { "id": "connection-4", "source": "api", "target": "discovery", "label": "Discovery controls", "kind": "next", "direction": "both" }, { "id": "connection-5", "source": "discovery", "target": "search", "label": "Search / evidence", "kind": "next", "direction": "both" }, { "id": "connection-6", "source": "discovery", "target": "research", "label": "Prepared evidence", "kind": "next", "direction": "forward" }, { "id": "connection-7", "source": "research", "target": "store", "label": "Jobs / reviews", "kind": "next", "direction": "both" }, { "id": "connection-8", "source": "research", "target": "review", "label": "Reviewed draft", "kind": "next", "direction": "forward" }, { "id": "connection-9", "source": "review", "target": "store", "label": "Authority / history", "kind": "next", "direction": "both" }, { "id": "connection-10", "source": "review", "target": "gmail", "label": "Send / reconcile", "kind": "next", "direction": "both" }, { "id": "connection-11", "source": "api", "target": "optional", "label": "Configured calls", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "lead-finder-workflow", "name": "MehrLogic Lead Finder · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through MehrLogic Lead Finder.", "notes": [ "In-house macOS product", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "Discovery and evidence research feed a reviewed outreach pipeline with durable case history.\n\nDiscover a company\nFind an eligible organization within the chosen scope.\n\nPrepare evidence\nCheck the website, recipient, and relevant business facts.\n\nPrepare an introduction\nDraft from supported evidence and the case history.\n\nReady to send?\nCheck evidence, contact, history, saved authorization, and provider availability.\n\nHold for resolution\nKeep unsupported, changed, or uncertain work held with a reason.\n\nSend when authorized\nSend only after current checks allow delivery.\n\nReconcile conversation\nTrack replies and delivery state before considering the next action.\n\nUpdate the case\nRecord the outcome and the next appropriate step.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Discover a company", "actor": "Discovery", "description": "Find an eligible organization within the chosen scope.", "checks": [], "phase": "Workflow" }, { "id": "research", "kind": "process", "title": "Prepare evidence", "actor": "Research", "description": "Check the website, recipient, and relevant business facts.", "checks": [], "phase": "Workflow" }, { "id": "draft", "kind": "process", "title": "Prepare an introduction", "actor": "AI drafting", "description": "Draft from supported evidence and the case history.", "checks": [], "phase": "Workflow" }, { "id": "review", "kind": "decision", "title": "Ready to send?", "actor": "Review + authority", "description": "Check evidence, contact, history, saved authorization, and provider availability.", "checks": [], "phase": "Workflow" }, { "id": "hold", "kind": "end", "title": "Hold for resolution", "actor": "Case board", "description": "Keep unsupported, changed, or uncertain work held with a reason.", "checks": [], "phase": "Workflow" }, { "id": "send", "kind": "api", "title": "Send when authorized", "actor": "Gmail", "description": "Send only after current checks allow delivery.", "checks": [], "phase": "Workflow" }, { "id": "reply", "kind": "process", "title": "Reconcile conversation", "actor": "Reply + delivery sync", "description": "Track replies and delivery state before considering the next action.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Update the case", "actor": "Conversation / closed", "description": "Record the outcome and the next appropriate step.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "research", "label": "", "kind": "next" }, { "id": "transition-1", "source": "research", "target": "draft", "label": "", "kind": "next" }, { "id": "transition-2", "source": "draft", "target": "review", "label": "", "kind": "next" }, { "id": "transition-3", "source": "review", "target": "hold", "label": "A check holds", "kind": "branch" }, { "id": "transition-4", "source": "review", "target": "send", "label": "Checks allow", "kind": "branch" }, { "id": "transition-5", "source": "send", "target": "reply", "label": "", "kind": "next" }, { "id": "transition-6", "source": "reply", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "pantry-architecture", "name": "Pantry · System architecture", "projectId": "mehrlogic-architecture", "description": "An owner-only receipt PWA keeps uploads as durable drafts. Cloudflare Workers coordinate D1 records, R2 files and explicitly submitted Azure receipt analysis; reviewed records alone enter spending totals.", "notes": [ "Private receipt web app", "Architecture source reviewed October 14, 2026.", "Receipt routes, D1/R2 bindings and transport code inspected; no private receipts or live Azure analysis were accessed." ], "presentationNotes": "Pantry separates captured receipts from reviewed spending records. Manual entry works without Azure. Files are durable in R2; draft metadata, scan operation references and integer-cent values live in D1.\n\nThe private Sites identity boundary precedes an owner-scoped Worker API. An explicit scan starts Azure analysis, then polling reads that same operation. Refreshing never automatically submits another paid POST. The user reviews results before totals change.\n\nThe Azure key is encrypted server-side with a separate deployment secret. Receipt files and financial records stay private. This design has no independent background queue: the browser polls recoverable server-side scan state.\n\nReview scope\nReceipt routes, D1/R2 bindings and transport code inspected; no private receipts or live Azure analysis were accessed.", "diagramType": "architecture", "groups": [ { "id": "browser", "title": "Receipt PWA", "description": "Capture, manual entry, field review and spending views" }, { "id": "worker", "title": "Private Sites application", "description": "Owner-scoped Cloudflare Worker API and durable storage" }, { "id": "azure", "title": "Optional receipt extraction", "description": "User-configured Azure Document Intelligence resource" } ], "nodes": [ { "id": "ui", "kind": "frontend", "title": "Capture and review", "actor": "React · Vinext PWA", "description": "Upload images/PDFs, resize decodable images, or enter a receipt manually. Review extracted fields, refunds and integer-cent amounts before saving; monthly/annual views use saved receipts.", "checks": [], "phase": "Receipt PWA", "groupId": "browser" }, { "id": "api", "kind": "api", "title": "Receipt and scan API", "actor": "Cloudflare Worker · Sites identity", "description": "Enforce owner-scoped access, Origin checks, upload validation and configuration isolation. Reuse duplicate file drafts and persist the operation reference before subsequent polling.", "checks": [], "phase": "Private Sites application", "groupId": "worker" }, { "id": "data", "kind": "database", "title": "Receipt records and scan state", "actor": "Cloudflare D1", "description": "Store drafts, saved receipt fields, line items, integer-cent amounts, scan references and AES-GCM-encrypted Azure keys bound to the account. API reads never return a saved key.", "checks": [], "phase": "Private Sites application", "groupId": "worker" }, { "id": "files", "kind": "database", "title": "Receipt images and PDFs", "actor": "Cloudflare R2", "description": "Persist private original uploads separately from receipt metadata; access passes through the owner-scoped application API.", "checks": [], "phase": "Private Sites application", "groupId": "worker" }, { "id": "model", "kind": "external", "title": "Receipt analysis operation", "actor": "Azure prebuilt-receipt", "description": "An explicit POST starts first-page analysis. GET reads the existing operation; refreshes do not replay paid analysis. Uncertain/expired operations allow manual entry or a deliberate new scan.", "checks": [], "phase": "Optional receipt extraction", "groupId": "azure" } ], "edges": [ { "id": "connection-1", "source": "ui", "target": "api", "label": "Upload / review", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "api", "target": "data", "label": "Drafts / saved data", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "api", "target": "files", "label": "Private files", "kind": "next", "direction": "both" }, { "id": "connection-4", "source": "api", "target": "model", "label": "Submit / poll", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "pantry-workflow", "name": "Pantry · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Pantry.", "notes": [ "Private receipt web app", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "Uploaded receipts stay as drafts until reviewed data becomes searchable spending records.\n\nCapture a receipt\nCreate an uploaded draft, or begin with manual entry.\n\nKeep a draft\nPreserve the uploaded file before reviewed amounts count.\n\nExtract receipt details\nA requested analysis returns fields; manual entry also works.\n\nReview and correct\nCheck store, date, USD amounts, refund signs, and line items.\n\nSave the receipt?\nOnly reviewed and saved receipts contribute to spending.\n\nKeep the draft\nUnreviewed or unsaved receipts remain outside the totals.\n\nSave reviewed records\nPersist normalized metadata and item rows.\n\nExplore spending\nSearch items and compare monthly or annual saved spending.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Capture a receipt", "actor": "Photo or upload", "description": "Create an uploaded draft, or begin with manual entry.", "checks": [], "phase": "Workflow" }, { "id": "draft", "kind": "database", "title": "Keep a draft", "actor": "Durable receipt", "description": "Preserve the uploaded file before reviewed amounts count.", "checks": [], "phase": "Workflow" }, { "id": "scan", "kind": "api", "title": "Extract receipt details", "actor": "Azure / manual fields", "description": "A requested analysis returns fields; manual entry also works.", "checks": [], "phase": "Workflow" }, { "id": "review", "kind": "human", "title": "Review and correct", "actor": "Receipt editor", "description": "Check store, date, USD amounts, refund signs, and line items.", "checks": [], "phase": "Workflow" }, { "id": "decision", "kind": "decision", "title": "Save the receipt?", "actor": "User decision", "description": "Only reviewed and saved receipts contribute to spending.", "checks": [], "phase": "Workflow" }, { "id": "hold", "kind": "end", "title": "Keep the draft", "actor": "No totals yet", "description": "Unreviewed or unsaved receipts remain outside the totals.", "checks": [], "phase": "Workflow" }, { "id": "save", "kind": "database", "title": "Save reviewed records", "actor": "D1", "description": "Persist normalized metadata and item rows.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Explore spending", "actor": "Search + summaries", "description": "Search items and compare monthly or annual saved spending.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "draft", "label": "", "kind": "next" }, { "id": "transition-1", "source": "draft", "target": "scan", "label": "", "kind": "next" }, { "id": "transition-2", "source": "scan", "target": "review", "label": "", "kind": "next" }, { "id": "transition-3", "source": "review", "target": "decision", "label": "", "kind": "next" }, { "id": "transition-4", "source": "decision", "target": "hold", "label": "Keep editing", "kind": "branch" }, { "id": "transition-5", "source": "decision", "target": "save", "label": "Save", "kind": "branch" }, { "id": "transition-6", "source": "save", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "story-teller-architecture", "name": "Story Teller · System architecture", "projectId": "mehrlogic-architecture", "description": "An invite-only Railway studio turns recordings or written stories into private audio. A separately gated public listener serves only deliberately published recordings; long narration jobs use persisted reservations and sequential speech parts.", "notes": [ "Invite-only studio · public stories", "Architecture source reviewed October 14, 2026.", "Public welcome page and current source inspected; no invited studio records, provider calls or private audio were accessed.", "Cloudflare migration remains a deferred option; the diagram shows Railway." ], "presentationNotes": "The studio and listener share one Railway application but have different access rules. Invited verified authors own private recordings and written stories. Publishing deliberately creates a public listening surface, with visibility rechecked on every media read.\n\nSpeech jobs persist a whole-story reservation and unique request identity before calling Azure. Long stories run in sequential parts; FFmpeg combines validated complete audio. Job progress survives refreshes, and interrupted paid work is not blindly retried.\n\nFirestore holds metadata, invitations and discussions; the persistent Railway volume holds private audio and artwork. The PWA caches a generic offline shell rather than private stories, audio or paid requests. Custom voices and AI writing remain separate configuration gates.\n\nReview scope\nPublic welcome page and current source inspected; no invited studio records, provider calls or private audio were accessed.\nCloudflare migration remains a deferred option; the diagram shows Railway.", "diagramType": "architecture", "groups": [ { "id": "browser", "title": "Studio and public listening", "description": "PWA authorship and publication-controlled playback" }, { "id": "server", "title": "Railway application", "description": "One Express process, durable job state and a private persistent volume" }, { "id": "storage", "title": "Private application storage", "description": "Server-only records and persistent audio bytes" }, { "id": "services", "title": "Identity and speech", "description": "Firebase account sessions and configured Azure Speech" } ], "nodes": [ { "id": "studio", "kind": "frontend", "title": "Invite-only story studio", "actor": "PWA · record / paste / review", "description": "Record or upload originals, edit text, request narration/transcription, organize albums/playlists and choose publication. Paid actions require the current server-verified administrator role.", "checks": [], "phase": "Studio and public listening", "groupId": "browser" }, { "id": "listener", "kind": "frontend", "title": "Public story player", "actor": "Published audio · comments", "description": "Stream only explicitly public recordings. Comments require an invited verified session. Public responses omit private account, file and budget fields.", "checks": [], "phase": "Studio and public listening", "groupId": "browser" }, { "id": "api", "kind": "api", "title": "Story and publication API", "actor": "Node.js · Express", "description": "Check invitations, verified sessions, ownership, CSRF and publication on each request. Create/redeem a short-lived one-use installed-app sign-in handoff when explicitly requested.", "checks": [], "phase": "Railway application", "groupId": "server" }, { "id": "jobs", "kind": "service", "title": "Durable speech job runner", "actor": "Sequential parts · FFmpeg", "description": "Atomically reserve account/studio allowance and claim operation identity. Split long text, synthesize sequential parts, validate audio and combine complete results. Interrupted paid jobs are not automatically replayed.", "checks": [], "phase": "Railway application", "groupId": "server" }, { "id": "db", "kind": "database", "title": "Stories, jobs and discussions", "actor": "Server-only Firestore", "description": "Store author-scoped stories, job progress, reservations, invitation roles, playlists, publication/discussions and listening statistics. Browser clients have no direct Firestore write access.", "checks": [], "phase": "Private application storage", "groupId": "storage" }, { "id": "audio", "kind": "database", "title": "Private audio and artwork", "actor": "Railway persistent volume", "description": "Keep source recordings, generated narration, playback copies and covers outside public assets. The API gates private/public streams; startup/periodic cleanup removes expiring temporary files.", "checks": [], "phase": "Private application storage", "groupId": "storage" }, { "id": "auth", "kind": "external", "title": "Invitations and verified sessions", "actor": "Firebase Authentication", "description": "Verify invited accounts and issue HttpOnly backend session cookies. PWA installation does not grant access; a handoff retains the original session expiry.", "checks": [], "phase": "Identity and speech", "groupId": "services" }, { "id": "azure", "kind": "external", "title": "Narration and transcription", "actor": "Azure Speech", "description": "Perform explicitly confirmed speech operations under persistent application allowances. Prebuilt English/Farsi narrators are distinct from separately gated custom-voice enrollment and optional story writing.", "checks": [], "phase": "Identity and speech", "groupId": "services" } ], "edges": [ { "id": "connection-1", "source": "studio", "target": "api", "label": "Studio", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "listener", "target": "api", "label": "Listen", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "api", "target": "db", "label": "Records", "kind": "next", "direction": "both" }, { "id": "connection-4", "source": "api", "target": "jobs", "label": "Start job", "kind": "next", "direction": "forward" }, { "id": "connection-5", "source": "jobs", "target": "audio", "label": "Audio", "kind": "next", "direction": "forward" }, { "id": "connection-6", "source": "api", "target": "audio", "label": "Streams", "kind": "next", "direction": "both" }, { "id": "connection-7", "source": "api", "target": "auth", "label": "Session", "kind": "next", "direction": "both" }, { "id": "connection-8", "source": "jobs", "target": "azure", "label": "Speech", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "story-teller-workflow", "name": "Story Teller · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Story Teller.", "notes": [ "Invite-only studio · public stories", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "A private story studio coordinates long narration jobs, durable media, and deliberate public publishing.\n\nPrepare a story\nCreate text or review an explicitly transcribed original recording.\n\nChoose voice and confirm\nReview the operation estimate and selected English or Farsi voice.\n\nReserve the operation\nAssociate the request identity with the persistent account and studio reservation.\n\nNarrate sequential parts\nSplit long text and process each part with progress updates.\n\nValidate and combine\nCheck parts and complete audio; partial output is not published.\n\nSave in the private gallery\nSave complete audio for preview and download.\n\nPublish this recording?\nPublication is a separate deliberate choice.\n\nKeep it private\nOnly the owner can access the recording.\n\nMake it listenable\nExpose the selected audio and public story details.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Prepare a story", "actor": "Write or record", "description": "Create text or review an explicitly transcribed original recording.", "checks": [], "phase": "Workflow" }, { "id": "confirm", "kind": "human", "title": "Choose voice and confirm", "actor": "Studio", "description": "Review the operation estimate and selected English or Farsi voice.", "checks": [], "phase": "Workflow" }, { "id": "reserve", "kind": "database", "title": "Reserve the operation", "actor": "Atomic budget checks", "description": "Associate the request identity with the persistent account and studio reservation.", "checks": [], "phase": "Workflow" }, { "id": "parts", "kind": "process", "title": "Narrate sequential parts", "actor": "Azure Speech", "description": "Split long text and process each part with progress updates.", "checks": [], "phase": "Workflow" }, { "id": "merge", "kind": "process", "title": "Validate and combine", "actor": "FFmpeg", "description": "Check parts and complete audio; partial output is not published.", "checks": [], "phase": "Workflow" }, { "id": "private", "kind": "database", "title": "Save in the private gallery", "actor": "Owner workspace", "description": "Save complete audio for preview and download.", "checks": [], "phase": "Workflow" }, { "id": "decision", "kind": "decision", "title": "Publish this recording?", "actor": "Author decision", "description": "Publication is a separate deliberate choice.", "checks": [], "phase": "Workflow" }, { "id": "keep", "kind": "end", "title": "Keep it private", "actor": "Private playback", "description": "Only the owner can access the recording.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Make it listenable", "actor": "Public story", "description": "Expose the selected audio and public story details.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "confirm", "label": "", "kind": "next" }, { "id": "transition-1", "source": "confirm", "target": "reserve", "label": "", "kind": "next" }, { "id": "transition-2", "source": "reserve", "target": "parts", "label": "", "kind": "next" }, { "id": "transition-3", "source": "parts", "target": "merge", "label": "", "kind": "next" }, { "id": "transition-4", "source": "merge", "target": "private", "label": "", "kind": "next" }, { "id": "transition-5", "source": "private", "target": "decision", "label": "", "kind": "next" }, { "id": "transition-6", "source": "decision", "target": "keep", "label": "Private", "kind": "branch" }, { "id": "transition-7", "source": "decision", "target": "end", "label": "Publish", "kind": "branch" } ] }, { "version": 1, "id": "motion-studio-architecture", "name": "Motion Studio · System architecture", "projectId": "mehrlogic-architecture", "description": "The portfolio Motion Studio prototype runs on loopback, validates a selected photo/video and prepares a short clip with FFmpeg. Optional confirmed Gemini editing returns private local output; metadata may use local JSON or configured Firestore.", "notes": [ "Experimental photo-guided prototype", "Architecture source reviewed October 14, 2026.", "Historical prototype scope verified from its dedicated history and retained adapter/storage source; no video generation was submitted.", "Current Freehand desktop features are intentionally outside this portfolio entry." ], "presentationNotes": "This diagram covers the photo-guided portfolio prototype documented in prototype history. The later Freehand desktop direction is a separate product scope.\n\nThe browser talks only to an owner-scoped loopback Express server. FFmpeg prepares a short clip and previews; the free demo leaves the original identity unchanged. A paid Gemini request needs explicit confirmation and returns private local output.\n\nMetadata defaults to local JSON and can use configured Firestore. Media bytes stay on the computer. Request identity and reservations survive failures; output quality still requires human playback review. Retention resumes when the local process restarts.\n\nReview scope\nHistorical prototype scope verified from its dedicated history and retained adapter/storage source; no video generation was submitted.\nCurrent Freehand desktop features are intentionally outside this portfolio entry.", "diagramType": "architecture", "groups": [ { "id": "browser", "title": "Local editing interface", "description": "Source selection, confirmation and output review" }, { "id": "local", "title": "Local prototype process", "description": "One owner-scoped Express server and private media directory" }, { "id": "files", "title": "Private local storage", "description": "Media bytes and default job metadata remain on the computer" }, { "id": "cloud", "title": "Configured external services", "description": "Optional metadata persistence and explicit video generation" } ], "nodes": [ { "id": "ui", "kind": "frontend", "title": "Photo and video editor", "actor": "Browser · local session", "description": "Choose a source photo and movement clip, preview the prepared segment and confirm a paid edit. The free demo is a watermarked copy of the original clip, not an AI replacement.", "checks": [], "phase": "Local editing interface", "groupId": "browser" }, { "id": "api", "kind": "api", "title": "Loopback prototype API", "actor": "Express · session / CSRF", "description": "Validate uploads, Host/Origin and owner session. Manage one active generation, persisted request identity and reservation state without automatically replaying uncertain paid requests.", "checks": [], "phase": "Local prototype process", "groupId": "local" }, { "id": "ffmpeg", "kind": "service", "title": "Media preparation", "actor": "FFmpeg · FFprobe", "description": "Inspect media, normalize inputs, trim the selected segment and create previews. Review timing, identity and motion fidelity after generation.", "checks": [], "phase": "Local prototype process", "groupId": "local" }, { "id": "store", "kind": "database", "title": "Private media and local records", "actor": "Private files · JSON default", "description": "Keep input/output bytes outside public assets with owner-only permissions. Default metadata is local; expiry cleanup runs at startup and while the process remains open.", "checks": [], "phase": "Private local storage", "groupId": "files" }, { "id": "model", "kind": "external", "title": "Confirmed video-edit adapter", "actor": "Gemini Interactions REST", "description": "Send only selected prepared inputs on explicit confirmation, with store:false and background:false. Save returned bytes privately; do not automatically repeat an uncertain generation.", "checks": [], "phase": "Configured external services", "groupId": "cloud" }, { "id": "metadata", "kind": "database", "title": "Optional metadata store", "actor": "Configured Firestore", "description": "When configured, persist jobs, assets, instructions and allowance records in server-only Firestore. Media bytes remain local; a namespace supports one server instance.", "checks": [], "phase": "Configured external services", "groupId": "cloud" } ], "edges": [ { "id": "connection-1", "source": "ui", "target": "api", "label": "Preview / confirm", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "api", "target": "ffmpeg", "label": "Inspect / trim", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "ffmpeg", "target": "store", "label": "Prepared clips", "kind": "next", "direction": "forward" }, { "id": "connection-4", "source": "api", "target": "store", "label": "Jobs / media", "kind": "next", "direction": "both" }, { "id": "connection-5", "source": "api", "target": "model", "label": "Confirmed edit", "kind": "next", "direction": "both" }, { "id": "connection-6", "source": "api", "target": "metadata", "label": "Optional metadata", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "motion-studio-workflow", "name": "Motion Studio · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Motion Studio.", "notes": [ "Experimental photo-guided prototype", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "The portfolio prototype validates media, prepares a short edit, and tracks one explicitly confirmed generation job.\n\nChoose media\nSelect the photo and source video used by the portfolio prototype.\n\nValidate and select a clip\nCheck media and prepare a short segment.\n\nReview the operation\nInspect the source preview and the requested edit.\n\nGenerate or preview?\nA free preview trims the source; generation is explicitly confirmed.\n\nView the source trim\nA source trim is not AI-generated output.\n\nSubmit one edit\nRecord request identity and reservation before submitting the paid edit.\n\nReview and download\nInspect identity and motion quality before using the result.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Choose media", "actor": "Photo + video", "description": "Select the photo and source video used by the portfolio prototype.", "checks": [], "phase": "Workflow" }, { "id": "validate", "kind": "process", "title": "Validate and select a clip", "actor": "Local preparation", "description": "Check media and prepare a short segment.", "checks": [], "phase": "Workflow" }, { "id": "review", "kind": "human", "title": "Review the operation", "actor": "Preview + estimate", "description": "Inspect the source preview and the requested edit.", "checks": [], "phase": "Workflow" }, { "id": "decision", "kind": "decision", "title": "Generate or preview?", "actor": "User choice", "description": "A free preview trims the source; generation is explicitly confirmed.", "checks": [], "phase": "Workflow" }, { "id": "preview", "kind": "end", "title": "View the source trim", "actor": "Free preview", "description": "A source trim is not AI-generated output.", "checks": [], "phase": "Workflow" }, { "id": "generate", "kind": "api", "title": "Submit one edit", "actor": "Gemini adapter", "description": "Record request identity and reservation before submitting the paid edit.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Review and download", "actor": "Experimental output", "description": "Inspect identity and motion quality before using the result.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "validate", "label": "", "kind": "next" }, { "id": "transition-1", "source": "validate", "target": "review", "label": "", "kind": "next" }, { "id": "transition-2", "source": "review", "target": "decision", "label": "", "kind": "next" }, { "id": "transition-3", "source": "decision", "target": "preview", "label": "Preview only", "kind": "branch" }, { "id": "transition-4", "source": "decision", "target": "generate", "label": "Confirm generation", "kind": "branch" }, { "id": "transition-5", "source": "generate", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "knowledge-wiki-architecture", "name": "Knowledge Wiki · System architecture", "projectId": "mehrlogic-architecture", "description": "A local Markdown knowledge system preserves original sources and maintains linked summaries, indexes and provenance. Humans or explicitly authorized agents read and update files; no background RAG server or vector database is specified.", "notes": [ "Private Markdown knowledge system", "Architecture source reviewed October 14, 2026.", "Reviewed system instructions and directory conventions only; personal journals, medical notes and source contents were not read.", "No independent background scheduler or vector retrieval service was established by the inspected system definition." ], "presentationNotes": "Knowledge Wiki is a filesystem knowledge architecture. Obsidian and authorized agents operate on Markdown, retained source assets and links, rather than calling a hosted application backend.\n\nRaw sources preserve what was originally observed. Maintained wiki pages synthesize those sources while keeping provenance, contradictions and open questions visible. A source register, index and processing log make updates traceable.\n\nRetrieval starts from a user question or an explicitly authorized maintenance task. Templates and routines guide the work; they do not imply a deployed vector database, autonomous crawler or account connector. Personal note content was not needed for this review.\n\nReview scope\nReviewed system instructions and directory conventions only; personal journals, medical notes and source contents were not read.\nNo independent background scheduler or vector retrieval service was established by the inspected system definition.", "diagramType": "architecture", "groups": [ { "id": "capture", "title": "Capture and original evidence", "description": "User notes, clippings and immutable dated source copies" }, { "id": "knowledge", "title": "Local Markdown workspace", "description": "Maintained synthesis with links and an append-only processing trail" }, { "id": "context", "title": "Human and authorized agent", "description": "Scoped reading, synthesis and evidence-backed retrieval" } ], "nodes": [ { "id": "inbox", "kind": "human", "title": "Notes, inbox and clippings", "actor": "Obsidian · user capture", "description": "Collect user-authored notes and deliberately selected material in inbox/clipping areas. Capture is separate from a maintained conclusion.", "checks": [], "phase": "Capture and original evidence", "groupId": "capture" }, { "id": "raw", "kind": "database", "title": "Retained original sources", "actor": "raw/ · originals and assets", "description": "Preserve dated source text and supporting assets. New evidence is added as a new source rather than rewriting an original.", "checks": [], "phase": "Capture and original evidence", "groupId": "capture" }, { "id": "wiki", "kind": "database", "title": "Maintained knowledge pages", "actor": "wiki/ · linked Markdown", "description": "Synthesize project context, source summaries and decisions with citations to originals. Distinguish evidence, inference, contradictions and unresolved questions.", "checks": [], "phase": "Local Markdown workspace", "groupId": "knowledge" }, { "id": "register", "kind": "database", "title": "Source register and processing log", "actor": "Provenance · append-only log", "description": "Map retained sources to maintained pages and record what was ingested or changed. This is file-based provenance rather than an external database service.", "checks": [], "phase": "Local Markdown workspace", "groupId": "knowledge" }, { "id": "index", "kind": "service", "title": "Indexes, links and templates", "actor": "Obsidian navigation · capture routines", "description": "Connect concise pages, source notes and open questions. Templates guide repeatable capture; links make subsequent retrieval inspectable.", "checks": [], "phase": "Local Markdown workspace", "groupId": "knowledge" }, { "id": "reader", "kind": "human", "title": "Scoped context and synthesis", "actor": "Human / explicitly authorized agent", "description": "Read relevant local evidence and maintain pages within the requested scope. A documented routine alone does not establish a running scheduler or automatic access to external accounts.", "checks": [], "phase": "Human and authorized agent", "groupId": "context" } ], "edges": [ { "id": "connection-1", "source": "inbox", "target": "raw", "label": "Retained input", "kind": "next", "direction": "forward" }, { "id": "connection-7", "source": "reader", "target": "wiki", "label": "Scoped synthesis", "kind": "next", "direction": "forward" }, { "id": "connection-4", "source": "wiki", "target": "register", "label": "Page provenance", "kind": "next", "direction": "both" }, { "id": "connection-5", "source": "wiki", "target": "index", "label": "Linked pages", "kind": "next", "direction": "forward" }, { "id": "connection-6", "source": "index", "target": "reader", "label": "Relevant context", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "raw", "target": "register", "label": "Source mapping", "kind": "next", "direction": "forward" }, { "id": "connection-2", "source": "raw", "target": "wiki", "label": "Cited evidence", "kind": "next", "direction": "forward" } ] }, { "version": 1, "id": "knowledge-wiki-workflow", "name": "Knowledge Wiki · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Knowledge Wiki.", "notes": [ "Private Markdown knowledge system", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "Original sources, linked summaries, and reusable capture routines make project context retrievable.\n\nCapture material\nSelect the information to retain.\n\nPreserve the original\nRetain source wording before synthesis.\n\nRead relevant evidence\nCheck what the source actually supports.\n\nMaintain linked pages\nUpdate a concise summary with source references and unresolved questions.\n\nUpdate traceability\nRecord the source-to-page links and meaningful changes.\n\nRetrieve useful context\nUse linked pages and originals when continuing the work.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Capture material", "actor": "User notes", "description": "Select the information to retain.", "checks": [], "phase": "Workflow" }, { "id": "preserve", "kind": "database", "title": "Preserve the original", "actor": "Source snapshot", "description": "Retain source wording before synthesis.", "checks": [], "phase": "Workflow" }, { "id": "read", "kind": "process", "title": "Read relevant evidence", "actor": "Scoped research", "description": "Check what the source actually supports.", "checks": [], "phase": "Workflow" }, { "id": "synthesize", "kind": "process", "title": "Maintain linked pages", "actor": "Project context", "description": "Update a concise summary with source references and unresolved questions.", "checks": [], "phase": "Workflow" }, { "id": "index", "kind": "database", "title": "Update traceability", "actor": "Register + index", "description": "Record the source-to-page links and meaningful changes.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Retrieve useful context", "actor": "Local workspace", "description": "Use linked pages and originals when continuing the work.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "preserve", "label": "", "kind": "next" }, { "id": "transition-1", "source": "preserve", "target": "read", "label": "", "kind": "next" }, { "id": "transition-2", "source": "read", "target": "synthesize", "label": "", "kind": "next" }, { "id": "transition-3", "source": "synthesize", "target": "index", "label": "", "kind": "next" }, { "id": "transition-4", "source": "index", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "daylight-architecture", "name": "Daylight · System architecture", "projectId": "mehrlogic-architecture", "description": "Obsidian edits shared Markdown on the laptop. Syncthing exchanges only that vault with an Ubuntu kiosk, whose local Python server and Firefox display keep reminder acknowledgements and note history outside the synchronized files.", "notes": [ "Obsidian calendar and reminder kiosk", "Architecture source reviewed October 14, 2026.", "Inspected Python store/server, browser polling and kiosk launcher; no Ubuntu session or physical sound test was performed." ], "presentationNotes": "There are two independent computers and one synchronized task-file set. Obsidian writes Markdown on the laptop. Syncthing moves task notes and attachments to Ubuntu, and later carries kiosk completions back.\n\nFirefox talks only to the Ubuntu loopback Python server and polls every five seconds. The server computes reminders from local files and writes accepted task changes atomically. Snoozes, dismissals and old-note history use private runtime storage outside the synchronized folder.\n\nDesktop login starts the kiosk session and its wake inhibitor. Existing local files remain usable offline, with synchronization catching up later. A chime in the UI does not prove the physical speaker output works.\n\nReview scope\nInspected Python store/server, browser polling and kiosk launcher; no Ubuntu session or physical sound test was performed.", "diagramType": "architecture", "groups": [ { "id": "laptop", "title": "Laptop authoring", "description": "Obsidian writes local task files; Syncthing moves files" }, { "id": "ubuntu", "title": "Ubuntu kiosk", "description": "Local display/API, synchronized task copy and private reminder state" } ], "nodes": [ { "id": "obsidian", "kind": "frontend", "title": "Obsidian task editor", "actor": "Markdown · attachments", "description": "Edit task notes and linked documents directly in the laptop vault. Obsidian does not call the kiosk API.", "checks": [], "phase": "Laptop authoring", "groupId": "laptop" }, { "id": "laptop-vault", "kind": "database", "title": "Shared Daylight vault", "actor": "Local Markdown and documents", "description": "Store portable task definitions and attachments. Completions/reschedules arriving from the kiosk are ordinary synced file changes.", "checks": [], "phase": "Laptop authoring", "groupId": "laptop" }, { "id": "laptop-sync", "kind": "infrastructure", "title": "Laptop file synchronization", "actor": "Syncthing · paired folder", "description": "Exchange only the designated vault; reconnect and propagate queued file changes after offline work.", "checks": [], "phase": "Laptop authoring", "groupId": "laptop" }, { "id": "startup", "kind": "infrastructure", "title": "Desktop startup and wake guard", "actor": "User login · GNOME inhibitor", "description": "Start the installed local services and launch Firefox in kiosk mode after desktop login. Hold idle/suspend inhibition while the display runs.", "checks": [], "phase": "Ubuntu kiosk", "groupId": "ubuntu" }, { "id": "browser", "kind": "frontend", "title": "Firefox day view", "actor": "Kiosk · five-second polling", "description": "Poll local task/reminder state; display due tasks, open documents, and submit snooze, dismissal, completion or rescheduling actions. Chimes require enabled sound and working physical output.", "checks": [], "phase": "Ubuntu kiosk", "groupId": "ubuntu" }, { "id": "server", "kind": "api", "title": "Daylight local API", "actor": "Python HTTP · loopback", "description": "Read and validate task Markdown, calculate reminders and accept local HTTP changes. Use revision-aware note edits and atomic file writes; no cloud backend is required.", "checks": [], "phase": "Ubuntu kiosk", "groupId": "ubuntu" }, { "id": "ubuntu-vault", "kind": "database", "title": "Shared vault replica", "actor": "Synced Markdown and documents", "description": "Hold Ubuntu task and attachment files. Server edits become file synchronization back to Obsidian.", "checks": [], "phase": "Ubuntu kiosk", "groupId": "ubuntu" }, { "id": "ubuntu-sync", "kind": "infrastructure", "title": "Ubuntu file synchronization", "actor": "Syncthing · paired folder", "description": "Synchronize the designated vault with the laptop in both directions; private runtime state is excluded.", "checks": [], "phase": "Ubuntu kiosk", "groupId": "ubuntu" }, { "id": "state", "kind": "database", "title": "Private reminder state and history", "actor": "SQLite · runtime history", "description": "Persist snooze/dismissal acknowledgements and prior note revisions outside the synchronized vault. These records are local to the kiosk.", "checks": [], "phase": "Ubuntu kiosk", "groupId": "ubuntu" } ], "edges": [ { "id": "connection-8", "source": "server", "target": "state", "label": "Reminder state", "kind": "next", "direction": "both" }, { "id": "connection-1", "source": "obsidian", "target": "laptop-vault", "label": "Edit files", "kind": "next", "direction": "both" }, { "id": "connection-6", "source": "browser", "target": "server", "label": "Local HTTP", "kind": "next", "direction": "both" }, { "id": "connection-5", "source": "startup", "target": "browser", "label": "Launch kiosk", "kind": "next", "direction": "forward" }, { "id": "connection-7", "source": "server", "target": "ubuntu-vault", "label": "Tasks / edits", "kind": "next", "direction": "both" }, { "id": "connection-4", "source": "ubuntu-sync", "target": "ubuntu-vault", "label": "Vault files", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "laptop-sync", "target": "ubuntu-sync", "label": "Two-way sync", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "laptop-vault", "target": "laptop-sync", "label": "Vault files", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "daylight-workflow", "name": "Daylight · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Daylight.", "notes": [ "Obsidian calendar and reminder kiosk", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "Two computers share task files while the kiosk keeps its reminder acknowledgements local.\n\nWrite a task in Obsidian\nSet the schedule and link any required documents.\n\nSynchronize vault files\nTransfer task notes and attachments to the kiosk.\n\nRead tasks and reminders\nCompute the day view and due reminder state from local files and history.\n\nShow the day and reminder\nPresent the next task and due reminders. A chime depends on enabled sound.\n\nComplete or acknowledge?\nTask edits and reminder acknowledgements have different storage boundaries.\n\nKeep acknowledgement local\nStore reminder acknowledgement only in private Ubuntu state.\n\nUpdate the task note\nWrite task status or its next repeat date to the vault.\n\nReturn the edit to Obsidian\nSynchronize changed task files when both devices can connect.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Write a task in Obsidian", "actor": "Laptop", "description": "Set the schedule and link any required documents.", "checks": [], "phase": "Workflow" }, { "id": "sync", "kind": "process", "title": "Synchronize vault files", "actor": "Syncthing", "description": "Transfer task notes and attachments to the kiosk.", "checks": [], "phase": "Workflow" }, { "id": "read", "kind": "process", "title": "Read tasks and reminders", "actor": "Python server", "description": "Compute the day view and due reminder state from local files and history.", "checks": [], "phase": "Workflow" }, { "id": "display", "kind": "human", "title": "Show the day and reminder", "actor": "Firefox", "description": "Present the next task and due reminders. A chime depends on enabled sound.", "checks": [], "phase": "Workflow" }, { "id": "decision", "kind": "decision", "title": "Complete or acknowledge?", "actor": "Kiosk user", "description": "Task edits and reminder acknowledgements have different storage boundaries.", "checks": [], "phase": "Workflow" }, { "id": "private", "kind": "end", "title": "Keep acknowledgement local", "actor": "Snooze / dismiss", "description": "Store reminder acknowledgement only in private Ubuntu state.", "checks": [], "phase": "Workflow" }, { "id": "complete", "kind": "database", "title": "Update the task note", "actor": "Complete / reschedule", "description": "Write task status or its next repeat date to the vault.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Return the edit to Obsidian", "actor": "Two-way sync", "description": "Synchronize changed task files when both devices can connect.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "sync", "label": "", "kind": "next" }, { "id": "transition-1", "source": "sync", "target": "read", "label": "", "kind": "next" }, { "id": "transition-2", "source": "read", "target": "display", "label": "", "kind": "next" }, { "id": "transition-3", "source": "display", "target": "decision", "label": "", "kind": "next" }, { "id": "transition-4", "source": "decision", "target": "private", "label": "Snooze or dismiss", "kind": "branch" }, { "id": "transition-5", "source": "decision", "target": "complete", "label": "Complete or edit", "kind": "branch" }, { "id": "transition-6", "source": "complete", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "pathways-architecture", "name": "Pathways · System architecture", "projectId": "mehrlogic-architecture", "description": "Firebase Hosting fronts a revisioned Next.js workspace on Cloud Run. Firestore stores projects, diagrams and authoring sessions; optional hosted AI jobs use Cloud Tasks and return validated drafts for explicit atomic Apply.", "notes": [ "Private hosted workspace", "Architecture source reviewed October 14, 2026.", "Current queue, worker, provider and transfer implementations inspected; older core-only architecture prose omits the later AI queue.", "No generation job or production workspace mutation was performed for this review." ], "presentationNotes": "The browser contains roadmaps, workflow and architecture editors, layout and local drafts. Firebase Hosting routes to a single Cloud Run Next.js application. Firebase Authentication establishes a verified server session; all data access passes through trusted APIs.\n\nOrdinary saves compare revisions and merge stale drafts. Complete-project bundles preserve diagram order, groups, directions, links and presenter notes. Duplicate single-diagram IDs offer a reviewed replacement or a fresh copy.\n\nThe current AI path adds Cloud Tasks even though the older core architecture document describes no queue. A named task invokes an OIDC-protected worker endpoint on the same app. The worker claims durable Firestore state, rechecks access, runs the configured provider and saves a draft. Explicit Apply atomically checks the project base and saves the reviewed set.\n\nReview scope\nCurrent queue, worker, provider and transfer implementations inspected; older core-only architecture prose omits the later AI queue.\nNo generation job or production workspace mutation was performed for this review.", "diagramType": "architecture", "groups": [ { "id": "client", "title": "Browser workspace", "description": "Roadmaps, workflows, architectures and reviewable drafts" }, { "id": "app", "title": "Hosted Next.js application", "description": "Cloud Run pages/API, domain rules and authenticated AI worker" }, { "id": "services", "title": "Managed workspace services", "description": "Firebase identity, Firestore and a task queue" }, { "id": "providers", "title": "Optional AI providers", "description": "Enabled hosted Astra or Gemini inference" } ], "nodes": [ { "id": "ui", "kind": "frontend", "title": "Planning and Architecture UI", "actor": "React · Next.js", "description": "Edit roadmaps, workflows and grouped architecture maps. Inspect components and presenter notes, preview imports and select Replace existing or Import as copy on ID conflicts.", "checks": [], "phase": "Browser workspace", "groupId": "client" }, { "id": "layout", "kind": "service", "title": "Diagram geometry and editor", "actor": "ELK · architecture router", "description": "Arrange the selected diagram and fit/pan/zoom its canvas without altering dependency semantics. Route labels using their full text footprint.", "checks": [], "phase": "Browser workspace", "groupId": "client" }, { "id": "sync", "kind": "service", "title": "Revisioned saves and transfers", "actor": "Drafts · three-way merge · v1 bundles", "description": "Keep unsaved drafts, reject stale writes and resolve conflicts. Complete-project exports retain diagrams/order/internal links/presenter notes; credentials and conversations do not transfer.", "checks": [], "phase": "Browser workspace", "groupId": "client" }, { "id": "api", "kind": "api", "title": "Workspace API and pages", "actor": "Next.js · Cloud Run / Hosting", "description": "Firebase Hosting forwards pages and __session to the app. Validate Origin, verified session, project access, request shape and individual diagram revisions.", "checks": [], "phase": "Hosted Next.js application", "groupId": "app" }, { "id": "store", "kind": "service", "title": "Domain rules and atomic Apply", "actor": "Workspace / flow repositories", "description": "Apply task semantics and membership rules. Reviewed authoring proposals compare the complete saved base and commit diagram definitions plus order atomically.", "checks": [], "phase": "Hosted Next.js application", "groupId": "app" }, { "id": "worker", "kind": "service", "title": "Authoring worker endpoint", "actor": "OIDC · durable job claims", "description": "Receive authenticated Cloud Tasks calls at the same Cloud Run app, recheck account/project access, claim each job once, run the tool loop and persist the result. Duplicate dispatch cannot start another generation.", "checks": [], "phase": "Hosted Next.js application", "groupId": "app" }, { "id": "auth", "kind": "external", "title": "Verified sign-in sessions", "actor": "Firebase Authentication", "description": "Exchange verified browser Google identity for HttpOnly server sessions. Backend authorization remains authoritative for every protected operation.", "checks": [], "phase": "Managed workspace services", "groupId": "services" }, { "id": "db", "kind": "database", "title": "Projects, diagrams and AI state", "actor": "Server-only Firestore", "description": "Persist revisioned workspace/flow records, sessions, jobs and Apply receipts through transactions. Browsers have no direct Firestore writer.", "checks": [], "phase": "Managed workspace services", "groupId": "services" }, { "id": "queue", "kind": "queue", "title": "Durable AI task dispatch", "actor": "Google Cloud Tasks", "description": "Dispatch named jobs with a signed OIDC identity and bounded deadlines. Queue retries reuse job identity; interrupted generation is not blindly replayed.", "checks": [], "phase": "Managed workspace services", "groupId": "services" }, { "id": "ai", "kind": "external", "title": "Configured hosted authoring", "actor": "Astra / Gemini", "description": "Generate through structured tools and schema validation. Enabled-provider settings govern availability; a successful model response remains a draft until Apply.", "checks": [], "phase": "Optional AI providers", "groupId": "providers" } ], "edges": [ { "id": "connection-1", "source": "ui", "target": "layout", "label": "Definition / geometry", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "ui", "target": "sync", "label": "Draft / snapshot", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "sync", "target": "api", "label": "Save / transfer", "kind": "next", "direction": "both" }, { "id": "connection-4", "source": "api", "target": "auth", "label": "Verify session", "kind": "next", "direction": "both" }, { "id": "connection-5", "source": "ui", "target": "auth", "label": "Google sign-in", "kind": "next", "direction": "both" }, { "id": "connection-6", "source": "api", "target": "store", "label": "Access / validation", "kind": "next", "direction": "forward" }, { "id": "connection-7", "source": "store", "target": "db", "label": "Revisioned records", "kind": "next", "direction": "both" }, { "id": "connection-8", "source": "api", "target": "queue", "label": "Queue job", "kind": "next", "direction": "forward" }, { "id": "connection-9", "source": "queue", "target": "worker", "label": "OIDC dispatch", "kind": "next", "direction": "forward" }, { "id": "connection-10", "source": "worker", "target": "db", "label": "Claim / result", "kind": "next", "direction": "both" }, { "id": "connection-11", "source": "worker", "target": "ai", "label": "Authoring tools", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "pathways-workflow", "name": "Pathways · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Pathways.", "notes": [ "Private hosted workspace", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "A shared planning and flow-authoring interface saves validated, revisioned projects through one trusted application.\n\nChoose a project\nOpen a roadmap or application flow in the workspace.\n\nEdit or author a diagram\nCreate steps or grouped components and explain their relationships.\n\nValidate the domain\nCheck references, branches, group assignments, and graph consistency.\n\nIs the revision current?\nCompare the saved revision before changing shared state.\n\nReview a merge\nMerge or resolve other edits before saving again.\n\nPersist the change\nWrite a validated project or flow revision atomically.\n\nPresent or export\nExplore the diagram or export its flows and presenter notes.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Choose a project", "actor": "Shared workspace", "description": "Open a roadmap or application flow in the workspace.", "checks": [], "phase": "Workflow" }, { "id": "edit", "kind": "human", "title": "Edit or author a diagram", "actor": "User / AI draft", "description": "Create steps or grouped components and explain their relationships.", "checks": [], "phase": "Workflow" }, { "id": "validate", "kind": "process", "title": "Validate the domain", "actor": "Pathways rules", "description": "Check references, branches, group assignments, and graph consistency.", "checks": [], "phase": "Workflow" }, { "id": "revision", "kind": "decision", "title": "Is the revision current?", "actor": "Server comparison", "description": "Compare the saved revision before changing shared state.", "checks": [], "phase": "Workflow" }, { "id": "conflict", "kind": "end", "title": "Review a merge", "actor": "Stale draft", "description": "Merge or resolve other edits before saving again.", "checks": [], "phase": "Workflow" }, { "id": "save", "kind": "database", "title": "Persist the change", "actor": "Firestore transaction", "description": "Write a validated project or flow revision atomically.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Present or export", "actor": "Portable project", "description": "Explore the diagram or export its flows and presenter notes.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "edit", "label": "", "kind": "next" }, { "id": "transition-1", "source": "edit", "target": "validate", "label": "", "kind": "next" }, { "id": "transition-2", "source": "validate", "target": "revision", "label": "", "kind": "next" }, { "id": "transition-3", "source": "revision", "target": "conflict", "label": "Stale revision", "kind": "branch" }, { "id": "transition-4", "source": "revision", "target": "save", "label": "Current revision", "kind": "branch" }, { "id": "transition-5", "source": "save", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "pathways-local-architecture", "name": "Pathways Local · System architecture", "projectId": "mehrlogic-architecture", "description": "One loopback Docker application provides roadmaps, workflows and architecture maps with SQLite persistence. Users can author manually, submit local-agent proposals without a Pathways key, or optionally supply their own Astra API key.", "notes": [ "Local app · open source", "Architecture source reviewed October 14, 2026.", "The architecture includes the released local-agent proposal and atomic Apply APIs. Optional Astra remains a separate user-key connection.", "Cross-edition schema/layout compatibility is checked locally; these new review projects have not been uploaded to the private workspace." ], "presentationNotes": "All core planning, workflow and architecture features run in one Docker application bound to loopback. A named volume holds SQLite and private server configuration. No Firebase account or managed subscription is required.\n\nThere are three authoring paths: manual edits, an external local agent using the discoverable API/CLI, and optional Astra with a user-supplied key. The agent path submits validated proposals without asking Pathways to call a model. Astra jobs use an in-process tool loop with durable job claims.\n\nAll generated content first becomes a reviewable draft. Apply compares the saved base and atomically saves the complete set and order. Version-1 project bundles carry architecture/workflow definitions, links and presenter notes between supporting editions while leaving keys and conversations behind.\n\nReview scope\nThe architecture includes the released local-agent proposal and atomic Apply APIs. Optional Astra remains a separate user-key connection.\nComplete-project exports use the shared version-1 format and exclude credentials and authoring conversations.", "diagramType": "architecture", "groups": [ { "id": "browser", "title": "Local authoring tools", "description": "Browser workspace and an explicitly chosen local agent" }, { "id": "container", "title": "Single Docker application", "description": "Next.js API, validation and in-process optional AI runner" }, { "id": "volume", "title": "Persistent local volume", "description": "Workspace, durable proposal state and separate private key file" }, { "id": "provider", "title": "Optional user-key inference", "description": "Astra usage billed to the user-supplied OpenAI key" } ], "nodes": [ { "id": "ui", "kind": "frontend", "title": "Planning and Architecture UI", "actor": "React · diagrams / presenter notes", "description": "Create roadmaps, workflows and architecture maps with groups and two-way links. Preview JSON/AI edits, fit/expand the canvas and review before saving.", "checks": [], "phase": "Local authoring tools", "groupId": "browser" }, { "id": "sync", "kind": "service", "title": "Drafts, merge and portable transfer", "actor": "Revisioned edits · v1 bundles", "description": "Handle stale tabs and reviewed Replace existing / Import as copy. Complete-project transfers preserve order, internal links and presenter notes across supporting private/local versions.", "checks": [], "phase": "Local authoring tools", "groupId": "browser" }, { "id": "agent", "kind": "human", "title": "Local agent and CLI", "actor": "Discover · read · propose · apply", "description": "Read project definitions and exact revision bases, validate and submit a proposal through localhost. The agent route makes no Pathways provider call and does not require an API key.", "checks": [], "phase": "Local authoring tools", "groupId": "browser" }, { "id": "api", "kind": "api", "title": "Local workspace and agent API", "actor": "Next.js · Host / Origin checks", "description": "Listen through the Docker loopback port and enforce local Host, Origin, client header and request validation. Expose normal workspace, transfer and discoverable agent routes.", "checks": [], "phase": "Single Docker application", "groupId": "container" }, { "id": "store", "kind": "service", "title": "Rules and atomic review/Apply", "actor": "Schemas · compare-and-swap", "description": "Validate complete definitions and project order. Proposals save a reviewable draft; Apply checks the exact base and atomically commits all reviewed changes plus receipt.", "checks": [], "phase": "Single Docker application", "groupId": "container" }, { "id": "runner", "kind": "service", "title": "Optional in-process Astra runner", "actor": "Responses tool loop · durable claim", "description": "Claim one queued local job after dispatch, call the configured provider outside database transactions and store draft/error state. This is the same application process, not an external worker fleet.", "checks": [], "phase": "Single Docker application", "groupId": "container" }, { "id": "db", "kind": "database", "title": "Persistent SQLite workspace", "actor": "Docker named volume · WAL", "description": "Store workspace, per-flow revisions, sessions/jobs/proposals and Apply receipts. WAL, synchronous FULL and transaction revision checks protect concurrent local saves.", "checks": [], "phase": "Persistent local volume", "groupId": "volume" }, { "id": "key", "kind": "database", "title": "Separate private API-key settings", "actor": "Mode-0600 server file", "description": "Store the optional user-supplied OpenAI key on the local server, separately from portable project data. Credentials, authoring conversations and job receipts are excluded from exports.", "checks": [], "phase": "Persistent local volume", "groupId": "volume" }, { "id": "astra", "kind": "external", "title": "Optional Astra API", "actor": "OpenAI · user-supplied key", "description": "Used only when configured and explicitly requested. The user key pays for API usage; Pathways Local has no hosted AI subscription. Core authoring and the agent API work without this connection.", "checks": [], "phase": "Optional user-key inference", "groupId": "provider" } ], "edges": [ { "id": "connection-1", "source": "ui", "target": "sync", "label": "Draft / transfer", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "sync", "target": "api", "label": "Local requests", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "agent", "target": "api", "label": "Propose / apply", "kind": "next", "direction": "both" }, { "id": "connection-4", "source": "api", "target": "store", "label": "Validated changes", "kind": "next", "direction": "forward" }, { "id": "connection-5", "source": "store", "target": "db", "label": "Atomic records", "kind": "next", "direction": "both" }, { "id": "connection-6", "source": "api", "target": "runner", "label": "Optional AI job", "kind": "next", "direction": "forward" }, { "id": "connection-7", "source": "runner", "target": "db", "label": "Claim / draft", "kind": "next", "direction": "both" }, { "id": "connection-8", "source": "runner", "target": "key", "label": "Server key", "kind": "next", "direction": "forward" }, { "id": "connection-9", "source": "runner", "target": "astra", "label": "Authoring tools", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "pathways-local-workflow", "name": "Pathways Local · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Pathways Local.", "notes": [ "Local app · open source", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "The planning interface and API run together in Docker with a revisioned SQLite workspace on the computer.\n\nOpen the local workspace\nRun the application locally; no cloud sign-in is required.\n\nEdit a roadmap or flow\nChange tasks, dependencies, decisions, or application flows.\n\nValidate the request\nCheck request origin and the domain’s rules.\n\nCan this revision save?\nAccept only the revision that still matches the persisted workspace.\n\nResolve another edit\nA stale tab receives the current content for review.\n\nCommit local state\nAtomically persist the accepted change in the volume.\n\nContinue or export\nReopen the workspace or transfer a complete project.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Open the local workspace", "actor": "Browser + Docker", "description": "Run the application locally; no cloud sign-in is required.", "checks": [], "phase": "Workflow" }, { "id": "edit", "kind": "human", "title": "Edit or review a generated diagram", "actor": "Planning interface", "description": "Edit a roadmap, workflow or architecture manually, or review an Astra/local-agent proposal before Apply.", "checks": [], "phase": "Workflow" }, { "id": "checks", "kind": "process", "title": "Validate the request", "actor": "Local API", "description": "Check request origin and the domain’s rules.", "checks": [], "phase": "Workflow" }, { "id": "revision", "kind": "decision", "title": "Can this revision save?", "actor": "SQLite comparison", "description": "A normal save checks its revision; proposal Apply checks the exact project base and commits the reviewed diagram set/order atomically.", "checks": [], "phase": "Workflow" }, { "id": "merge", "kind": "end", "title": "Resolve another edit", "actor": "Merge review", "description": "A stale tab receives the current content for review.", "checks": [], "phase": "Workflow" }, { "id": "save", "kind": "database", "title": "Commit local state", "actor": "SQLite", "description": "Atomically persist the accepted change in the volume.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Continue or export", "actor": "Local ownership", "description": "Reopen the workspace or transfer a complete project.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "edit", "label": "", "kind": "next" }, { "id": "transition-1", "source": "edit", "target": "checks", "label": "", "kind": "next" }, { "id": "transition-2", "source": "checks", "target": "revision", "label": "", "kind": "next" }, { "id": "transition-3", "source": "revision", "target": "merge", "label": "Stale revision", "kind": "branch" }, { "id": "transition-4", "source": "revision", "target": "save", "label": "Current revision", "kind": "branch" }, { "id": "transition-5", "source": "save", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "tree-events-architecture", "name": "Harvest at Home Tree Events · System architecture", "projectId": "mehrlogic-architecture", "description": "An Express/SQLite event app combines public tree adoption with protected administration. Free adoptions confirm directly; premium or fulfillment charges stay pending until signed Stripe payment, while post-adoption donations remain optional.", "notes": [ "Custom event application", "Architecture source reviewed October 14, 2026.", "Current index.js is ahead of README descriptions, including required-fee/premium and fulfillment paths.", "No public app URL or active payment/shipping configuration was verified; no adoption or payment was submitted.", "Inventory concurrency guarantees need a separate implementation review; this task documents the existing behavior." ], "presentationNotes": "The public adoption page and organizer tools share one Express/SQLite application. Organizer sessions use stored password hashes; inventory, event, adoption and audit data are local database records.\n\nCurrent source goes beyond the older optional-donation diagram. Free, no-fee adoptions record directly. Premium trees or required fulfillment charges first create a pending adoption; signed Stripe completion drives final confirmation with an inventory recheck. Optional post-adoption donations remain a separate path.\n\nPickup-location and configured USPS code are part of fulfillment. The inspected free path uses separate SQL writes, so this diagram does not claim transaction-level stock atomicity. Deployment availability and active provider configuration need an operational check.\n\nReview scope\nCurrent index.js is ahead of README descriptions, including required-fee/premium and fulfillment paths.\nNo public app URL or active payment/shipping configuration was verified; no adoption or payment was submitted.\nInventory concurrency guarantees need a separate implementation review; this task documents the existing behavior.", "diagramType": "architecture", "groups": [ { "id": "browser", "title": "Event interfaces", "description": "Public adoption and protected organizer tools" }, { "id": "app", "title": "Event application", "description": "One Express process, admin sessions and SQLite records" }, { "id": "payment", "title": "Configured payment and shipping", "description": "Stripe Checkout and USPS APIs when configured" } ], "nodes": [ { "id": "public", "kind": "frontend", "title": "Tree adoption and fulfillment", "actor": "Public event form", "description": "Select available trees and event, provide adoption details and choose configured pickup/shipping. Display required fees separately from an optional contribution.", "checks": [], "phase": "Event interfaces", "groupId": "browser" }, { "id": "admin", "kind": "frontend", "title": "Organizer administration", "actor": "Inventory · events · order history", "description": "Manage tree stock, premium-tree charges, events, pickup locations, adoptions and donation history behind an admin session.", "checks": [], "phase": "Event interfaces", "groupId": "browser" }, { "id": "api", "kind": "api", "title": "Adoption and checkout API", "actor": "Node.js · Express", "description": "Validate current inventory and fulfillment choices. A no-fee adoption records stock immediately; a required charge creates a pending adoption and waits for verified payment.", "checks": [], "phase": "Event application", "groupId": "app" }, { "id": "auth", "kind": "service", "title": "Protected admin sessions", "actor": "Hashed passwords · HttpOnly cookie", "description": "Verify stored password hashes and admin cookies; protect organizer routes with Origin/rate checks and record successful management actions in the audit log.", "checks": [], "phase": "Event application", "groupId": "app" }, { "id": "db", "kind": "database", "title": "Event and pending-adoption records", "actor": "SQLite file", "description": "Store trees/event stock, purchases, pending adoptions, pickup locations, admins, donations and audit records. Required-charge completion rechecks inventory; do not assume an inventory transaction where source performs separate SQL writes.", "checks": [], "phase": "Event application", "groupId": "app" }, { "id": "stripe", "kind": "external", "title": "Optional donations / required fees", "actor": "Stripe Checkout · signed webhook", "description": "Create configured Checkout sessions. Verify webhook signatures, record payment state and complete pending required-charge adoptions. A browser success page alone is not payment evidence.", "checks": [], "phase": "Configured payment and shipping", "groupId": "payment" }, { "id": "usps", "kind": "external", "title": "Configured shipping service", "actor": "USPS OAuth · prices / labels", "description": "Obtain fulfillment quotes and support the implemented shipping path when credentials exist. Public deployment and active provider settings were not established by this local source review.", "checks": [], "phase": "Configured payment and shipping", "groupId": "payment" } ], "edges": [ { "id": "connection-1", "source": "public", "target": "api", "label": "Adopt / fee status", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "admin", "target": "auth", "label": "Admin sign-in", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "auth", "target": "api", "label": "Protected access", "kind": "next", "direction": "forward" }, { "id": "connection-4", "source": "api", "target": "db", "label": "Stock / adoption", "kind": "next", "direction": "both" }, { "id": "connection-5", "source": "api", "target": "stripe", "label": "Checkout / webhook", "kind": "next", "direction": "both" }, { "id": "connection-6", "source": "api", "target": "usps", "label": "Shipping APIs", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "tree-events-workflow", "name": "Harvest at Home Tree Events · Main workflow", "projectId": "mehrlogic-architecture", "description": "Representative free/no-required-fee adoption path. Premium trees or required fulfillment charges instead stay pending until verified Stripe payment.", "notes": [ "Custom event application", "This map explains the documented behavior.", "Scope: the free/no-required-fee path only. See Architecture for the separate pending required-charge branch.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "A public adoption form and signed-in administration share event, inventory, adoption, and donation records.\n\nChoose available trees\nSelect tree types and an optional event.\n\nSubmit the adoption\nProvide the required adoption details.\n\nRecord adoption and stock\nCreate the adoption record and reduce inventory.\n\nAdd a donation?\nDonation checkout is optional after a successful adoption.\n\nContinue to donation checkout\nUse the configured donation flow.\n\nAdoption recorded\nThe adoption remains available to organizers.\n\nReview donation history\nOrganizers can review the adoption and available donation records.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Choose available trees", "actor": "Visitor", "description": "Select tree types and an optional event.", "checks": [], "phase": "Workflow" }, { "id": "submit", "kind": "human", "title": "Submit the adoption", "actor": "Public form", "description": "Provide the required adoption details.", "checks": [], "phase": "Workflow" }, { "id": "record", "kind": "database", "title": "Record adoption and stock", "actor": "Express + SQLite", "description": "Create the adoption record and reduce inventory.", "checks": [], "phase": "Workflow" }, { "id": "donate", "kind": "decision", "title": "Add a donation?", "actor": "Visitor choice", "description": "Donation checkout is optional after a successful adoption.", "checks": [], "phase": "Workflow" }, { "id": "checkout", "kind": "api", "title": "Continue to donation checkout", "actor": "Stripe", "description": "Use the configured donation flow.", "checks": [], "phase": "Workflow" }, { "id": "done", "kind": "end", "title": "Adoption recorded", "actor": "Event history", "description": "The adoption remains available to organizers.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Review donation history", "actor": "Admin workspace", "description": "Organizers can review the adoption and available donation records.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "submit", "label": "", "kind": "next" }, { "id": "transition-1", "source": "submit", "target": "record", "label": "", "kind": "next" }, { "id": "transition-2", "source": "record", "target": "donate", "label": "", "kind": "next" }, { "id": "transition-3", "source": "donate", "target": "done", "label": "No donation", "kind": "branch" }, { "id": "transition-4", "source": "donate", "target": "checkout", "label": "Donate", "kind": "branch" }, { "id": "transition-5", "source": "checkout", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "razor-resale-architecture", "name": "Razor Resale · System architecture", "projectId": "mehrlogic-architecture", "description": "Firebase-hosted shopping and workshop tools use a trusted Cloud Run commerce API. Signed payment events reconcile stock and durable shipping jobs; USPS labels/tracking and deduplicated SendGrid notifications complete fulfillment.", "notes": [ "Public commerce and workshop platform", "Architecture source reviewed October 14, 2026.", "Public storefront, current fulfillment code and October 13 deployment/activation documentation inspected; no live order or runtime secret was accessed." ], "presentationNotes": "Firebase Hosting serves the storefront, customer pages and workshop; /api goes to Express on Cloud Run. The API reads authoritative stock, price and package data from Firestore before reserving checkout quantities.\n\nSigned Stripe events commit payment outcomes idempotently. Accepted paid orders can create durable fulfillment jobs. A lease and persisted purchase intent protect USPS label creation; uncertain outcomes hold for original-label recovery rather than automatically purchasing again.\n\nAn authenticated scheduler resumes pending work. USPS tracking callbacks update durable fulfillment, and a deduplicated email outbox sends customer/seller notifications through SendGrid. Private labels and prepared product media are stored in Cloud Storage with application-controlled access.\n\nThe public site also exposes sharpening and lesson requests, while protected sourcing analysis remains optional. Operational activation is described by the checked-in deployment record; this review made no purchase, sent no email and changed no stock.\n\nReview scope\nPublic storefront, current fulfillment code and October 13 deployment/activation documentation inspected; no live order or runtime secret was accessed.", "diagramType": "architecture", "groups": [ { "id": "browser", "title": "Storefront and service tools", "description": "Public shopping, customer accounts and protected workshop" }, { "id": "server", "title": "Trusted commerce application", "description": "Cloud Run API, durable inventory/fulfillment and private media" }, { "id": "storage", "title": "Private records and media", "description": "Transactional business state and controlled object storage" }, { "id": "integrations", "title": "Identity and commerce providers", "description": "Verified accounts, payments and shipping" }, { "id": "automation", "title": "Recovery and optional analysis", "description": "Authenticated scheduler, mail delivery and sourcing AI" } ], "nodes": [ { "id": "storefront", "kind": "frontend", "title": "Public storefront and cart", "actor": "Firebase Hosting · browser modules", "description": "Browse published merchandise and create a cart. The server derives current item price, stock, package and fulfillment eligibility; client amounts are not trusted.", "checks": [], "phase": "Storefront and service tools", "groupId": "browser" }, { "id": "workshop", "kind": "frontend", "title": "Workshop, accounts and services", "actor": "Inventory · lessons · sharpening", "description": "Manage sourcing/restoration, stock and orders; customers use scoped account history and service-request interfaces. Lesson/sharpening payments have service-specific verification.", "checks": [], "phase": "Storefront and service tools", "groupId": "browser" }, { "id": "api", "kind": "api", "title": "Commerce and service API", "actor": "Express · Cloud Run", "description": "Verify account roles, coordinate inventory reservations and validate signed payment/tracking callbacks. Hosting proxies /api; no browser Firestore write access.", "checks": [], "phase": "Trusted commerce application", "groupId": "server" }, { "id": "fulfillment", "kind": "service", "title": "Shipping and notification jobs", "actor": "Durable leases · uncertain holds", "description": "After accepted payment, claim shipping work, persist a purchase intent and create/recover the original label. An uncertain label purchase cannot be blindly repeated; outbox keys deduplicate notifications.", "checks": [], "phase": "Trusted commerce application", "groupId": "server" }, { "id": "db", "kind": "database", "title": "Business records and job journal", "actor": "Firestore transactions", "description": "Persist inventory, reservations, orders, service requests, shipping jobs and email outbox. Payment completion/expiration reconcile the reserved units idempotently.", "checks": [], "phase": "Private records and media", "groupId": "storage" }, { "id": "media", "kind": "database", "title": "Private media and label files", "actor": "Cloud Storage · prepared variants", "description": "Store product image/video variants and private fulfillment labels. Application routes control publication and order-specific access.", "checks": [], "phase": "Private records and media", "groupId": "storage" }, { "id": "stripe", "kind": "external", "title": "Payments and signed events", "actor": "Stripe Checkout · Tax", "description": "Collect authorized checkout/service payments, calculate applicable checkout tax, and return signed completion/expiry events. Duplicate payment events do not duplicate stock or fulfillment.", "checks": [], "phase": "Identity and commerce providers", "groupId": "integrations" }, { "id": "usps", "kind": "external", "title": "Shipping rates, labels and tracking", "actor": "USPS OAuth · signed callbacks", "description": "Quote validated delivery addresses, purchase configured shipping labels and return tracking events. Uncertain creation uses original-label recovery rather than another purchase.", "checks": [], "phase": "Identity and commerce providers", "groupId": "integrations" }, { "id": "auth", "kind": "external", "title": "Verified customer and staff identity", "actor": "Firebase Authentication", "description": "Establish verified customer/staff access. Backend rules scope customer history and workshop operations.", "checks": [], "phase": "Identity and commerce providers", "groupId": "integrations" }, { "id": "scheduler", "kind": "infrastructure", "title": "Pending-shipping recovery", "actor": "Cloud Scheduler · OIDC", "description": "Call the protected pending-job endpoint on a schedule so interrupted fulfillment can resume. Scheduler identity is separate from a customer account.", "checks": [], "phase": "Recovery and optional analysis", "groupId": "automation" }, { "id": "mail", "kind": "external", "title": "Order and delivery notifications", "actor": "SendGrid · deduplicated outbox", "description": "Send configured customer/seller messages from durable accepted state, including label delivery and tracking milestones. A repeated event reuses the existing outbox entry.", "checks": [], "phase": "Recovery and optional analysis", "groupId": "automation" }, { "id": "ai", "kind": "external", "title": "Optional sourcing analysis", "actor": "OpenAI · protected workshop", "description": "Analyze candidate deals and inventory/service material only through configured authenticated operations. A source-supported analysis feature is not evidence of a current provider request.", "checks": [], "phase": "Recovery and optional analysis", "groupId": "automation" } ], "edges": [ { "id": "connection-1", "source": "storefront", "target": "api", "label": "Catalog / checkout", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "workshop", "target": "api", "label": "Protected tools", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "api", "target": "db", "label": "Stock / orders", "kind": "next", "direction": "both" }, { "id": "connection-4", "source": "api", "target": "media", "label": "Media / labels", "kind": "next", "direction": "both" }, { "id": "connection-5", "source": "api", "target": "fulfillment", "label": "Paid shipping", "kind": "next", "direction": "forward" }, { "id": "connection-6", "source": "fulfillment", "target": "db", "label": "Lease / outbox", "kind": "next", "direction": "both" }, { "id": "connection-7", "source": "api", "target": "stripe", "label": "Checkout / event", "kind": "next", "direction": "both" }, { "id": "connection-8", "source": "fulfillment", "target": "usps", "label": "Label / tracking", "kind": "next", "direction": "both" }, { "id": "connection-9", "source": "api", "target": "usps", "label": "Address / rates", "kind": "next", "direction": "both" }, { "id": "connection-10", "source": "api", "target": "auth", "label": "Verify identity", "kind": "next", "direction": "both" }, { "id": "connection-11", "source": "scheduler", "target": "fulfillment", "label": "OIDC recovery", "kind": "next", "direction": "forward" }, { "id": "connection-12", "source": "fulfillment", "target": "mail", "label": "Send once", "kind": "next", "direction": "forward" }, { "id": "connection-13", "source": "api", "target": "ai", "label": "Optional analysis", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "razor-resale-workflow", "name": "Razor Resale · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Razor Resale.", "notes": [ "Public commerce and workshop platform", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "A storefront and authenticated workshop connect stock, fulfillment, payments, media, and optional sourcing analysis.\n\nPublish prepared inventory\nPrepare product details, media, and the stock available for sale.\n\nBuild a cart\nChoose available merchandise from the storefront.\n\nValidate fulfillment\nCheck products and the selected fulfillment option; request a shipping estimate when needed.\n\nCreate payment checkout\nCreate the server-authorized checkout.\n\nIs payment verified?\nUse verified payment state before completing the order.\n\nKeep the order incomplete\nUnconfirmed payment does not establish a completed sale.\n\nUpdate stock and order\nReconcile the accepted payment with inventory and order records.\n\nManage fulfillment\nKeep the order available for fulfillment and account history.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Publish prepared inventory", "actor": "Workshop", "description": "Prepare product details, media, and the stock available for sale.", "checks": [], "phase": "Workflow" }, { "id": "shop", "kind": "human", "title": "Build a cart", "actor": "Customer", "description": "Choose available merchandise from the storefront.", "checks": [], "phase": "Workflow" }, { "id": "quote", "kind": "api", "title": "Validate fulfillment", "actor": "Commerce API", "description": "Check products and the selected fulfillment option; request a shipping estimate when needed.", "checks": [], "phase": "Workflow" }, { "id": "checkout", "kind": "api", "title": "Create payment checkout", "actor": "Stripe", "description": "Create the server-authorized checkout.", "checks": [], "phase": "Workflow" }, { "id": "verify", "kind": "decision", "title": "Is payment verified?", "actor": "Payment event", "description": "Use verified payment state before completing the order.", "checks": [], "phase": "Workflow" }, { "id": "hold", "kind": "end", "title": "Keep the order incomplete", "actor": "Payment not confirmed", "description": "Unconfirmed payment does not establish a completed sale.", "checks": [], "phase": "Workflow" }, { "id": "record", "kind": "database", "title": "Update stock and order", "actor": "Business records", "description": "Reconcile the accepted payment with inventory and order records.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Manage fulfillment", "actor": "Workshop + customer history", "description": "Accepted paid orders can start durable USPS label/tracking jobs and deduplicated notifications; uncertain purchases remain held for recovery.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "shop", "label": "", "kind": "next" }, { "id": "transition-1", "source": "shop", "target": "quote", "label": "", "kind": "next" }, { "id": "transition-2", "source": "quote", "target": "checkout", "label": "", "kind": "next" }, { "id": "transition-3", "source": "checkout", "target": "verify", "label": "", "kind": "next" }, { "id": "transition-4", "source": "verify", "target": "hold", "label": "Not confirmed", "kind": "branch" }, { "id": "transition-5", "source": "verify", "target": "record", "label": "Confirmed", "kind": "branch" }, { "id": "transition-6", "source": "record", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "harvest-at-home-architecture", "name": "Harvest at Home · System architecture", "projectId": "mehrlogic-architecture", "description": "A Firebase-hosted program website and separate tree storefront share a Cloud Run commerce service. Firestore coordinates stock and reservations; configured Maps/USPS and Stripe/SendGrid paths exist, while public checkout and online program donations remain closed.", "notes": [ "Public program site · checkout closed", "Architecture source reviewed October 14, 2026.", "Public homepage and commerce source/deployment documentation inspected; checkout remained closed and no payment, address lookup or mail was triggered." ], "presentationNotes": "The public program site emphasizes free trees through library programs and voluntary support. It links to a separate tree-purchase storefront. These are different journeys; future event signups and online program donations are not current commerce functionality.\n\nFirebase Hosting fronts an Express Cloud Run API. Dedicated Firestore records hold inventory, reservations and orders; private Cloud Storage holds imagery. The server checks shipping addresses or delivery routes before quoting fulfillment.\n\nStripe reconciliation and SendGrid order mail have documented sandbox verification and connected configuration. Public checkout is still disabled, and the live page says online program donations are coming later. The diagram shows those gates rather than implying an open paid storefront.\n\nReview scope\nPublic homepage and commerce source/deployment documentation inspected; checkout remained closed and no payment, address lookup or mail was triggered.", "diagramType": "architecture", "groups": [ { "id": "browser", "title": "Program and tree storefront", "description": "Free-program information, separate shop and staff tools" }, { "id": "server", "title": "Tree commerce application", "description": "Trusted Express API and dedicated cloud records/media" }, { "id": "services", "title": "Configured external services", "description": "Identity, payment, eligibility and order mail" } ], "nodes": [ { "id": "shop", "kind": "frontend", "title": "Tree shop and staff tools", "actor": "Catalog · fulfillment · admin", "description": "Browse the separate purchase catalog and choose supported shipping/delivery/pickup. Staff manage stock and orders. Public checkout remains disabled.", "checks": [], "phase": "Program and tree storefront", "groupId": "browser" }, { "id": "program", "kind": "frontend", "title": "Public library-program website", "actor": "Firebase Hosting · free-tree information", "description": "Describe free tree programs and voluntary support. Event-specific signup, pickup and donation behavior awaits requirements; online program donations are not yet implemented.", "checks": [], "phase": "Program and tree storefront", "groupId": "browser" }, { "id": "db", "kind": "database", "title": "Stock, reservations and orders", "actor": "Dedicated Firestore", "description": "Persist catalog, inventory, reservation expiry and order state. Demo mode is separate local sample data; test validation does not change live stock.", "checks": [], "phase": "Tree commerce application", "groupId": "server" }, { "id": "api", "kind": "api", "title": "Commerce and launch-gate API", "actor": "Express · Cloud Run", "description": "Validate authoritative stock, destination, chosen fulfillment and checkout availability. Signed payment events coordinate repeat-safe stock/order changes for the implemented payment path.", "checks": [], "phase": "Tree commerce application", "groupId": "server" }, { "id": "media", "kind": "database", "title": "Tree product images", "actor": "Private Cloud Storage", "description": "Store product imagery separately from business records and expose approved images through application routes.", "checks": [], "phase": "Tree commerce application", "groupId": "server" }, { "id": "auth", "kind": "external", "title": "Staff identity", "actor": "Firebase Authentication", "description": "Verify staff access for stock and order operations in the trusted API.", "checks": [], "phase": "Configured external services", "groupId": "services" }, { "id": "mail", "kind": "external", "title": "Configured order notifications", "actor": "SendGrid", "description": "Send accepted-order notifications through the configured domain. Program donation processing is a separate unimplemented workflow.", "checks": [], "phase": "Configured external services", "groupId": "services" }, { "id": "payment", "kind": "external", "title": "Configured payment path", "actor": "Stripe · signed webhook", "description": "Support server-authorized checkout and signed payment reconciliation. Sandbox coverage and connected credentials do not mean public checkout is open.", "checks": [], "phase": "Configured external services", "groupId": "services" }, { "id": "fulfillment", "kind": "external", "title": "Address and route eligibility", "actor": "Google Maps Routes · USPS", "description": "Check delivery route distance and shipping address/rates server-side. Shipping, local delivery and arranged pickup have separate validation rules.", "checks": [], "phase": "Configured external services", "groupId": "services" } ], "edges": [ { "id": "connection-4", "source": "api", "target": "media", "label": "Product images", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "api", "target": "db", "label": "Stock / reservations", "kind": "next", "direction": "both" }, { "id": "connection-8", "source": "api", "target": "mail", "label": "Order messages", "kind": "next", "direction": "forward" }, { "id": "connection-2", "source": "shop", "target": "api", "label": "Catalog / quotes", "kind": "next", "direction": "both" }, { "id": "connection-5", "source": "api", "target": "auth", "label": "Verify staff", "kind": "next", "direction": "both" }, { "id": "connection-1", "source": "program", "target": "shop", "label": "Separate shop", "kind": "next", "direction": "forward" }, { "id": "connection-7", "source": "api", "target": "payment", "label": "Gated checkout", "kind": "next", "direction": "both" }, { "id": "connection-6", "source": "api", "target": "fulfillment", "label": "Eligibility / rates", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "harvest-at-home-workflow", "name": "Harvest at Home · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Harvest at Home.", "notes": [ "Public program site · checkout closed", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "Program information and a separate tree storefront connect inventory, fulfillment eligibility, and tested payment workflows.\n\nExplore the program\nRead program information and open the separate tree catalog.\n\nChoose trees\nSelect products and a fulfillment option.\n\nCheck fulfillment eligibility\nValidate delivery area, pickup configuration, or shipping details.\n\nIs checkout available?\nThe public site currently keeps checkout closed.\n\nShow checkout status\nSelection does not create a live paid order while checkout is closed.\n\nRun the configured test flow\nThe tested path creates checkout and reconciles a signed payment event.\n\nReconcile stock and order\nApply verified order state and avoid repeat stock deduction.\n\nPrepare fulfillment and mail\nUse accepted order state for fulfillment and notifications.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Explore the program", "actor": "Public website", "description": "Read program information and open the separate tree catalog.", "checks": [], "phase": "Workflow" }, { "id": "select", "kind": "human", "title": "Choose trees", "actor": "Storefront", "description": "Select products and a fulfillment option.", "checks": [], "phase": "Workflow" }, { "id": "eligibility", "kind": "process", "title": "Check fulfillment eligibility", "actor": "Routes + addresses", "description": "Validate delivery area, pickup configuration, or shipping details.", "checks": [], "phase": "Workflow" }, { "id": "gate", "kind": "decision", "title": "Is checkout available?", "actor": "Launch gate", "description": "The public site currently keeps checkout closed.", "checks": [], "phase": "Workflow" }, { "id": "closed", "kind": "end", "title": "Show checkout status", "actor": "Public launch boundary", "description": "Selection does not create a live paid order while checkout is closed.", "checks": [], "phase": "Workflow" }, { "id": "test", "kind": "api", "title": "Run the configured test flow", "actor": "Sandbox checkout", "description": "The tested path creates checkout and reconciles a signed payment event.", "checks": [], "phase": "Workflow" }, { "id": "record", "kind": "database", "title": "Reconcile stock and order", "actor": "Firestore", "description": "Apply verified order state and avoid repeat stock deduction.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Prepare fulfillment and mail", "actor": "Order operations", "description": "Use accepted order state for fulfillment and notifications.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "select", "label": "", "kind": "next" }, { "id": "transition-1", "source": "select", "target": "eligibility", "label": "", "kind": "next" }, { "id": "transition-2", "source": "eligibility", "target": "gate", "label": "", "kind": "next" }, { "id": "transition-3", "source": "gate", "target": "closed", "label": "Public checkout closed", "kind": "branch" }, { "id": "transition-4", "source": "gate", "target": "test", "label": "Configured sandbox test", "kind": "branch" }, { "id": "transition-5", "source": "test", "target": "record", "label": "", "kind": "next" }, { "id": "transition-6", "source": "record", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "common-ground-architecture", "name": "Common Ground Center · System architecture", "projectId": "mehrlogic-architecture", "description": "A Cloud Run Express application serves public community content, patron registrations and protected administration. Firebase identity gates role-specific APIs; private Cloud Storage staging feeds FFmpeg optimization before application-controlled publication.", "notes": [ "Public content and community platform", "Architecture source reviewed October 14, 2026.", "Public site, registration transactions and media optimizer/storage implementation inspected; no patron record or upload was created.", "Future outbound program-email delivery is not represented as an active service." ], "presentationNotes": "The public website, patron account and administrator tools share a Cloud Run Express application. Firebase ID tokens establish verified identity; the API enforces current patron scope and a separate administrator allowlist.\n\nEvent registration creates an individual record and changes the public count in one Firestore transaction. Program-update subscriptions remain pending until verified. A verified subscriber list is not itself a deployed newsletter sender.\n\nMedia upload authorization, temporary staging, FFmpeg optimization and publication are separate lifecycle steps. The bucket stays private and approved media streams through the app. Encoding uses bounded work and low concurrency rather than an external transcoder fleet.\n\nReview scope\nPublic site, registration transactions and media optimizer/storage implementation inspected; no patron record or upload was created.\nFuture outbound program-email delivery is not represented as an active service.", "diagramType": "architecture", "groups": [ { "id": "browser", "title": "Community interfaces", "description": "Public reading and role-specific patron/admin tools" }, { "id": "app", "title": "Cloud Run application", "description": "Trusted API, transactional registration service and media optimization" }, { "id": "services", "title": "Identity and private storage", "description": "Verified Firebase users, Firestore and staged/published media" } ], "nodes": [ { "id": "site", "kind": "frontend", "title": "Public community website", "actor": "Programs · sermons · event counts", "description": "Read published content and aggregate registration counts. Subscription consent creates a pending verification flow, not automatic membership or a sent campaign.", "checks": [], "phase": "Community interfaces", "groupId": "browser" }, { "id": "account", "kind": "frontend", "title": "Patron and administrator tools", "actor": "Own registrations · admin rosters", "description": "Patrons register once per event and manage their own records. The allowed verified administrator edits content and views protected roster information.", "checks": [], "phase": "Community interfaces", "groupId": "browser" }, { "id": "api", "kind": "api", "title": "Role-aware community API", "actor": "Node.js · Express", "description": "Verify short-lived Firebase ID tokens, verified email and the admin allowlist. Apply rate limits and keep patron data scoped to the current account.", "checks": [], "phase": "Cloud Run application", "groupId": "app" }, { "id": "registrations", "kind": "service", "title": "Registration and verification service", "actor": "Firestore transactions", "description": "Update individual event registrations and aggregate counts in the same transaction. Keep new program subscriptions pending until Firebase email verification.", "checks": [], "phase": "Cloud Run application", "groupId": "app" }, { "id": "media", "kind": "service", "title": "Protected media optimization", "actor": "FFmpeg · bounded encode", "description": "Validate staged uploads, optimize image/audio/video and publish smaller output. Encoding runs within bounded request time and configured low concurrency.", "checks": [], "phase": "Cloud Run application", "groupId": "app" }, { "id": "auth", "kind": "external", "title": "Verified identities", "actor": "Firebase Google / email-link", "description": "Authenticate verified patrons and allowed administrators. No browser role field grants administration.", "checks": [], "phase": "Identity and private storage", "groupId": "services" }, { "id": "db", "kind": "database", "title": "Content and registration records", "actor": "Firestore", "description": "Persist content, verified/pending subscriptions, registrations and counts. Public routes expose aggregate counts; admin routes protect names/emails.", "checks": [], "phase": "Identity and private storage", "groupId": "services" }, { "id": "files", "kind": "database", "title": "Private staged and published media", "actor": "Google Cloud Storage", "description": "Accept authorized staged uploads; keep the bucket private. The application streams approved files through /media routes rather than exposing raw public objects. Lifecycle rules expire temporary staging.", "checks": [], "phase": "Identity and private storage", "groupId": "services" } ], "edges": [ { "id": "connection-1", "source": "site", "target": "api", "label": "Public content", "kind": "next", "direction": "both" }, { "id": "connection-2", "source": "account", "target": "auth", "label": "Google / email-link", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "account", "target": "api", "label": "Protected actions", "kind": "next", "direction": "both" }, { "id": "connection-4", "source": "api", "target": "auth", "label": "Verify ID token", "kind": "next", "direction": "both" }, { "id": "connection-5", "source": "api", "target": "registrations", "label": "Scoped operations", "kind": "next", "direction": "forward" }, { "id": "connection-6", "source": "registrations", "target": "db", "label": "Atomic counts", "kind": "next", "direction": "both" }, { "id": "connection-7", "source": "api", "target": "db", "label": "Published content", "kind": "next", "direction": "both" }, { "id": "connection-8", "source": "api", "target": "media", "label": "Process upload", "kind": "next", "direction": "forward" }, { "id": "connection-9", "source": "media", "target": "files", "label": "Stage / publish", "kind": "next", "direction": "both" }, { "id": "connection-10", "source": "api", "target": "files", "label": "Stream media", "kind": "next", "direction": "both" } ] }, { "version": 1, "id": "common-ground-workflow", "name": "Common Ground Center · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Common Ground Center.", "notes": [ "Public content and community platform", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "Public content, verified event accounts, and media publishing share a role-aware application service.\n\nFind a program or event\nRead the center’s published content and events.\n\nSign in as a patron\nUse the account flow to access personal event registrations.\n\nChoose an event\nSubmit or cancel a registration for that account.\n\nVerify account and request\nCheck verified identity and the user’s access.\n\nUpdate registration and count\nKeep individual registration state aligned with aggregate event counts.\n\nShow the right view\nReturn personal records to the patron, rosters to allowed admins, and only counts to public visitors.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Find a program or event", "actor": "Public website", "description": "Read the center’s published content and events.", "checks": [], "phase": "Workflow" }, { "id": "signin", "kind": "api", "title": "Sign in as a patron", "actor": "Verified identity", "description": "Use the account flow to access personal event registrations.", "checks": [], "phase": "Workflow" }, { "id": "register", "kind": "human", "title": "Choose an event", "actor": "Patron account", "description": "Submit or cancel a registration for that account.", "checks": [], "phase": "Workflow" }, { "id": "check", "kind": "process", "title": "Verify account and request", "actor": "Community API", "description": "Check verified identity and the user’s access.", "checks": [], "phase": "Workflow" }, { "id": "save", "kind": "database", "title": "Update registration and count", "actor": "Firestore transaction", "description": "Keep individual registration state aligned with aggregate event counts.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Show the right view", "actor": "Patron / admin / public", "description": "Return personal records to the patron, rosters to allowed admins, and only counts to public visitors.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "signin", "label": "", "kind": "next" }, { "id": "transition-1", "source": "signin", "target": "register", "label": "", "kind": "next" }, { "id": "transition-2", "source": "register", "target": "check", "label": "", "kind": "next" }, { "id": "transition-3", "source": "check", "target": "save", "label": "", "kind": "next" }, { "id": "transition-4", "source": "save", "target": "end", "label": "", "kind": "next" } ] }, { "version": 1, "id": "khidr-architecture", "name": "Khidr · System architecture", "projectId": "mehrlogic-architecture", "description": "Firebase Hosting fronts a trusted Cloud Run directory API with reviewed publisher ownership. Large videos use scoped resumable Cloud Storage uploads and a durable scheduler/Transcoder pipeline before verified output becomes public media.", "notes": [ "Public community atlas", "Architecture source reviewed October 14, 2026.", "Public atlas, video routes, journal and managed-job adapter inspected; no account, upload or paid transcoding request was created.", "Cloud resource settings follow the checked-in deployment record rather than a new production control-plane audit." ], "presentationNotes": "Firebase Hosting serves the public atlas and publisher tools, forwarding API calls and the server session cookie to Cloud Run. The Express API is the trusted data boundary. Verified identity, publisher approval and current community ownership are distinct requirements.\n\nThe newer video path is different from ordinary small-media uploads. The API reserves a quota slot and returns a scoped, create-only resumable session for a private source bucket. The browser uploads directly to that scoped session; it never receives permanent storage credentials.\n\nA signed scheduler maintains persisted upload journals and leases even after the browser closes. The server probes the source, submits Google Transcoder once, reconciles uncertain responses by label, validates output and rechecks current ownership before publication.\n\nPublic feeds and byte-range streams expose only approved media. Source lifecycle cleanup and publication are separate; abandoned uploads are not listed as public content. Optional Maps, Unsplash and Stripe configuration remains outside the verified active topology.\n\nReview scope\nPublic atlas, video routes, journal and managed-job adapter inspected; no account, upload or paid transcoding request was created.\nCloud resource settings follow the checked-in deployment record rather than a new production control-plane audit.", "diagramType": "architecture", "groups": [ { "id": "browser", "title": "Directory and publisher tools", "description": "Public discovery, ownership review and direct scoped video upload" }, { "id": "app", "title": "Trusted Cloud Run service", "description": "Express access rules, ownership and durable video coordination" }, { "id": "services", "title": "Identity and persistence", "description": "Verified sessions, records and separate private storage buckets" }, { "id": "video", "title": "Managed video processing", "description": "Authenticated maintenance scheduler and Google Transcoder" } ], "nodes": [ { "id": "directory", "kind": "frontend", "title": "Public community atlas", "actor": "Firebase Hosting · directory / media", "description": "Read public communities, gatherings, recent media and paginated feeds. Optional location is requested only for a user-selected nearby search.", "checks": [], "phase": "Directory and publisher tools", "groupId": "browser" }, { "id": "publisher", "kind": "frontend", "title": "Publisher and admin workspace", "actor": "Scoped edits · upload status", "description": "Verified publishers manage their assigned communities/events; admins review claims and transfers. The browser requests a scoped video upload session and reports completion.", "checks": [], "phase": "Directory and publisher tools", "groupId": "browser" }, { "id": "api", "kind": "api", "title": "Trusted Atlas API", "actor": "Express · Cloud Run", "description": "Verify HttpOnly Firebase server sessions and current roles. Enforce ownership on mutations, expose only public fields, and stream approved media through controlled routes.", "checks": [], "phase": "Trusted Cloud Run service", "groupId": "app" }, { "id": "ownership", "kind": "service", "title": "Ownership and publisher review", "actor": "Transactional claims / transfer", "description": "A requested publisher role or claim does not grant edit access. Review eligibility and current owner; preserve creator/history during an accepted transactional reassignment.", "checks": [], "phase": "Trusted Cloud Run service", "groupId": "app" }, { "id": "jobs", "kind": "service", "title": "Video upload and publication journal", "actor": "Leases · quota · FFprobe", "description": "Reserve slots and persist upload/job state in Firestore. Probe actual media before transcoding; reconcile uncertain job creation by label. Recheck ownership/event and validate output before publishing.", "checks": [], "phase": "Trusted Cloud Run service", "groupId": "app" }, { "id": "auth", "kind": "external", "title": "Verified account sessions", "actor": "Firebase Authentication", "description": "Verify email/password identities and issue __session cookies forwarded by Hosting. Verification and approved publisher eligibility remain separate checks.", "checks": [], "phase": "Identity and persistence", "groupId": "services" }, { "id": "db", "kind": "database", "title": "Directory and processing records", "actor": "Server-only Firestore", "description": "Store users, communities, events, claims, subscriptions, video journals and quota counters. Direct browser rules deny access; API transactions enforce consistency.", "checks": [], "phase": "Identity and persistence", "groupId": "services" }, { "id": "media", "kind": "database", "title": "Published media bucket", "actor": "Private Cloud Storage", "description": "Hold approved images/audio/documents and optimized video/posters. Pending or deleted objects do not appear in public feeds; API streaming supports byte ranges.", "checks": [], "phase": "Identity and persistence", "groupId": "services" }, { "id": "staging", "kind": "database", "title": "Private video-source bucket", "actor": "Resumable create-only sessions", "description": "Receive a size-bound browser upload authorized by the server, not a permanent bucket credential. Lifecycle cleanup expires successful sources and abandoned staging separately.", "checks": [], "phase": "Identity and persistence", "groupId": "services" }, { "id": "scheduler", "kind": "infrastructure", "title": "Video maintenance dispatch", "actor": "Cloud Scheduler · signed OIDC", "description": "Invoke a private maintenance endpoint to start/reconcile durable jobs even after the browser closes. A normal publisher session cannot invoke this scheduler route.", "checks": [], "phase": "Managed video processing", "groupId": "video" }, { "id": "transcoder", "kind": "external", "title": "Managed video conversion", "actor": "Google Transcoder", "description": "Read private source media and produce validated H.264/AAC video and poster objects outside the HTTP request. One-shot job identity prevents blind paid resubmission.", "checks": [], "phase": "Managed video processing", "groupId": "video" } ], "edges": [ { "id": "connection-9", "source": "jobs", "target": "db", "label": "Journal / quota", "kind": "next", "direction": "both" }, { "id": "connection-6", "source": "api", "target": "auth", "label": "Verify session", "kind": "next", "direction": "both" }, { "id": "connection-10", "source": "publisher", "target": "staging", "label": "Scoped upload", "kind": "next", "direction": "forward" }, { "id": "connection-2", "source": "publisher", "target": "api", "label": "Scoped changes", "kind": "next", "direction": "both" }, { "id": "connection-5", "source": "api", "target": "db", "label": "Content / roles", "kind": "next", "direction": "both" }, { "id": "connection-3", "source": "api", "target": "ownership", "label": "Claims / review", "kind": "next", "direction": "forward" }, { "id": "connection-4", "source": "ownership", "target": "db", "label": "Atomic ownership", "kind": "next", "direction": "both" }, { "id": "connection-11", "source": "jobs", "target": "staging", "label": "Probe / source", "kind": "next", "direction": "both" }, { "id": "connection-1", "source": "directory", "target": "api", "label": "Public listings", "kind": "next", "direction": "both" }, { "id": "connection-14", "source": "staging", "target": "transcoder", "label": "Source bytes", "kind": "next", "direction": "forward" }, { "id": "connection-7", "source": "api", "target": "media", "label": "Approved streams", "kind": "next", "direction": "both" }, { "id": "connection-15", "source": "transcoder", "target": "media", "label": "Video / poster", "kind": "next", "direction": "forward" }, { "id": "connection-13", "source": "jobs", "target": "transcoder", "label": "Submit / reconcile", "kind": "next", "direction": "both" }, { "id": "connection-12", "source": "scheduler", "target": "jobs", "label": "OIDC maintain", "kind": "next", "direction": "forward" }, { "id": "connection-8", "source": "api", "target": "jobs", "label": "Upload control", "kind": "next", "direction": "forward" } ] }, { "version": 1, "id": "khidr-workflow", "name": "Khidr · Main workflow", "projectId": "mehrlogic-architecture", "description": "A representative workflow through Khidr.", "notes": [ "Public community atlas", "This map explains the documented behavior.", "Source review: October 14, 2026; representative workflow retained alongside the refreshed architecture." ], "presentationNotes": "A searchable directory connects verified publisher access, community ownership, events, and media through a trusted API.\n\nFind a community\nSearch listings and gatherings.\n\nUse a verified publisher account\nSign in with the account’s current publisher eligibility.\n\nCan this publisher edit?\nCheck the community assignment and role.\n\nRequest ownership review\nSubmit supporting information for administrator review.\n\nWait for a decision\nA request alone does not transfer editing access.\n\nUpdate community content\nEdit the community and its connected events.\n\nValidate and save\nRecheck role and ownership before persisting content and media references.\n\nShow updated public content\nExpose public fields while private account and review details remain protected.", "diagramType": "workflow", "nodes": [ { "id": "start", "kind": "start", "title": "Find a community", "actor": "Public directory", "description": "Search listings and gatherings.", "checks": [], "phase": "Workflow" }, { "id": "signin", "kind": "api", "title": "Use a verified publisher account", "actor": "Account session", "description": "Sign in with the account’s current publisher eligibility.", "checks": [], "phase": "Workflow" }, { "id": "access", "kind": "decision", "title": "Can this publisher edit?", "actor": "Current ownership", "description": "Check the community assignment and role.", "checks": [], "phase": "Workflow" }, { "id": "request", "kind": "human", "title": "Request ownership review", "actor": "Claim or management change", "description": "Submit supporting information for administrator review.", "checks": [], "phase": "Workflow" }, { "id": "hold", "kind": "end", "title": "Wait for a decision", "actor": "Current owner retained", "description": "A request alone does not transfer editing access.", "checks": [], "phase": "Workflow" }, { "id": "edit", "kind": "human", "title": "Update community content", "actor": "Scoped publisher", "description": "Edit the community and its connected events.", "checks": [], "phase": "Workflow" }, { "id": "save", "kind": "database", "title": "Validate and save", "actor": "Trusted API", "description": "Recheck role and ownership before persisting content and media references.", "checks": [], "phase": "Workflow" }, { "id": "end", "kind": "end", "title": "Show updated public content", "actor": "Directory", "description": "Expose public fields while private account and review details remain protected.", "checks": [], "phase": "Workflow" } ], "edges": [ { "id": "transition-0", "source": "start", "target": "signin", "label": "", "kind": "next" }, { "id": "transition-1", "source": "signin", "target": "access", "label": "", "kind": "next" }, { "id": "transition-2", "source": "access", "target": "request", "label": "Review needed", "kind": "branch" }, { "id": "transition-3", "source": "request", "target": "hold", "label": "", "kind": "next" }, { "id": "transition-4", "source": "access", "target": "edit", "label": "Authorized owner", "kind": "branch" }, { "id": "transition-5", "source": "edit", "target": "save", "label": "", "kind": "next" }, { "id": "transition-6", "source": "save", "target": "end", "label": "", "kind": "next" } ] } ], "flowOrder": [ "meeting-copilot-architecture", "meeting-copilot-workflow", "lead-finder-architecture", "lead-finder-workflow", "pantry-architecture", "pantry-workflow", "story-teller-architecture", "story-teller-workflow", "motion-studio-architecture", "motion-studio-workflow", "knowledge-wiki-architecture", "knowledge-wiki-workflow", "daylight-architecture", "daylight-workflow", "pathways-architecture", "pathways-workflow", "pathways-local-architecture", "pathways-local-workflow", "tree-events-architecture", "tree-events-workflow", "razor-resale-architecture", "razor-resale-workflow", "harvest-at-home-architecture", "harvest-at-home-workflow", "common-ground-architecture", "common-ground-workflow", "khidr-architecture", "khidr-workflow" ] }