Skip to content
www.gimesha.com

Evidence-backed decisions

Engineering Decisions

Selected engineering decisions, the constraints behind them, and the public evidence that supports the trade-offs.

Systems software

Termstead

A native terminal product shell built around daemon-owned sessions and a client-owned workspace.

Keep workspace layout client-ownedWho owns terminal sessions and authoritative terminal state?accepted

Decision

The GUI owns windows, tabs, splits, focus, commands, and layout policy; the daemon owns terminal sessions.

Context

Termstead has a native product shell where workspace views and terminal sessions have different lifetimes.

Constraints

  • The daemon owns PTYs, child processes, terminal state, revisions, modes, and session lifetime.
  • The GUI owns windows, tabs, pane layout, focus, commands, and workspace policy.

Rationale

  • View composition can evolve without putting presentation policy into terminald or confusing a pane with a process.

Trade-offs

  • The split keeps presentation policy out of terminald, but the shell must maintain an explicit session/view binding across close, detach, reconnect, and termination.

Alternative considered

  • Daemon-owned workspace/layout was rejected because it would couple terminal authority to GUI presentation state.

Limitations

  • The evidence does not establish daemon persistence across crash, reboot, or power loss.
  • This is an ownership boundary, not a claim about complete GPUI product-shell functionality.

Evidence

  • Product-shell architecture

    Ownership, lifecycle semantics, IPC authority, renderer boundary, alternatives, and explicit non-goals.

    Pinned commit: f0889ba7ebf8d5585a20aedc22439dcc12b98472

  • Product shell lifecycle commands

    Pane/tab close, detach, explicit termination, and workspace-level view cleanup.

    Pinned commit: 0776a19f39539c396df76038c55a14bb55948a53

Use event-driven synchronization with snapshots and deltasWhich IPC messages carry authoritative terminal state?accepted

Decision

RenderReady wakes visible bindings; snapshots and revision-contiguous deltas remain authoritative.

Context

Visible sessions need updates without turning every pane into an independent polling loop.

Constraints

  • FullSnapshot and RenderDelta must preserve identity and revision continuity.
  • RenderReady may wake visible bindings but cannot replace authoritative state.

Rationale

  • The split reduces unnecessary polling while preserving recovery when a journal gap or reconnect invalidates incremental state.

Trade-offs

  • Wake hints reduce polling work, but gap and reconnect recovery still depends on snapshots and contiguous deltas.

Alternative considered

  • Per-pane polling and treating RenderReady as a state payload were rejected by the SessionHub design.

Limitations

  • This does not establish display, frame, or input-to-display latency.
  • The complete session-to-renderer lifecycle remains reserved for the future Systems Trace experience.

Evidence

  • SessionHub specification

    Approved bounded transport, identity, event, backpressure, and recovery contract.

    Pinned commit: 8ca581048f33a474f27f74b0a2c3e47c1b5364c6

  • SessionHub acceptance

    PASS WITH FOLLOW-UPS acceptance record with live Wayland and resource limitations.

    Pinned commit: 8ca581048f33a474f27f74b0a2c3e47c1b5364c6

  • SessionHub implementation

    Process-wide hub, binding identity, synchronization, visibility, recovery, and cleanup.

    Pinned commit: 0776a19f39539c396df76038c55a14bb55948a53

Developer tools

Platen PDF

A multi-repository document platform that separates the web workspace, Go API, and Python processing boundary.

Use response mode per workloadWhen should PDF work remain on the request path versus leave for a worker?implemented

Decision

Keep direct responses for bounded request work, queued jobs for long-running/progress-bearing operations, and a separate preview path for page inspection.

Context

Platen PDF exposes document tools with different result lifetimes: direct blobs, long-running jobs, and previews.

Constraints

  • The browser talks to the Go API; workers remain behind server-owned boundaries.
  • Long-running work needs explicit job state, artifact ownership, cancellation, and cleanup.

Rationale

  • The user experience and resource lifetime differ between a returned blob, a cancellable job, and a page image preview.

Trade-offs

  • Direct paths keep bounded results in the request, while asynchronous paths add job, storage, polling, cancellation, and cleanup state.

Alternative considered

  • Queueing every operation was not treated as the current design because several routes intentionally return synchronously.

Limitations

  • The source shows implementation boundaries, not throughput, scalability, or speed outcomes.
  • Not every document operation is asynchronous.

Evidence

  • Platen PDF frontend API boundary

    Configured API origin, multipart blob requests, error/health handling, and download-origin checks.

    Pinned commit: 70db8e8a5a1466ddb154112ed1ddecee6e6cb57e

  • Platen PDF Go API composition root

    API body/time limits, database/Redis startup, route registration, cleanup workers, and service composition.

    Pinned commit: 9faae1a42155843e0e5a6e472d6a4109ccaa25a8

  • Go OCR controller

    Synchronous and asynchronous OCR paths, cancellation polling, admission, result storage, billing release, and cleanup.

    Pinned commit: 9faae1a42155843e0e5a6e472d6a4109ccaa25a8

  • Go async PDF-to-Markdown route

    Validation, source-object staging, task registration, worker actor dispatch, and explicit dispatch failure handling.

    Pinned commit: 9faae1a42155843e0e5a6e472d6a4109ccaa25a8

  • Go preview session service

    Owner/content-keyed preview sessions, page rendering, session touch, recreation, and temporary PDF cleanup.

    Pinned commit: 9faae1a42155843e0e5a6e472d6a4109ccaa25a8

Keep platen-document optional and standaloneWhy is platen-document related to Platen PDF without being a required service?accepted

Decision

Treat platen-document as a related local-first SDK selected through explicit application adapters, not as a required Platen PDF web/API/worker service.

Context

The portfolio groups the web/API/worker product with a separately published document-processing SDK.

Constraints

  • Application-owned jobs, queues, storage, auth, billing, and UI remain outside the SDK.

Rationale

  • The SDK can be tested and used locally while the application retains jobs, queues, storage, auth, billing, and UI concerns.

Trade-offs

  • The separation keeps the SDK local-first and reusable, but integration requires explicit application adapters and does not collapse the product into one runtime.

Alternative considered

  • Merging the SDK into the product runtime or presenting it as a mandatory service would misstate its documented architecture.

Limitations

  • This relationship does not prove production deployment, throughput, or scalability.

Evidence

  • platen-document public API

    DocumentProcessor API, native/scanned routing, callbacks, searchable-PDF result reuse, markup, and local capability boundary.

    Pinned commit: a5a14413ded0daa93a5839b86554f1fe67d92a93

  • platen-document architecture

    Explicit SDK/application boundary, supported consumer selectors, and excluded auth/job/storage concerns.

    Pinned commit: a5a14413ded0daa93a5839b86554f1fe67d92a93

Financial systems

Banking Platform

A multi-client banking system spanning a Spring Boot core, Next.js web application, Android client, and FastAPI KYC service.

Keep authorization server-ownedWhat does Android device security protect, and what remains server-owned?implemented

Decision

Use Spring Security route/method guards, JWT validation, server-side session activity, and owner checks for protected resources.

Context

Banking Platform spans a Spring API, Next.js/React web client, and Android client with client-side navigation and token handling.

Constraints

  • Protected resources must enforce authentication, roles, ownership, and session validity at the API boundary.
  • Android Keystore and encryption protect local token storage; they do not decide server authorization.

Rationale

  • Client route guards improve navigation but cannot replace the core API's authorization boundary.

Trade-offs

  • Client guards improve navigation and local protection, but the server must repeat authorization checks and can reject stale or invalid tokens.

Alternative considered

  • Relying on web/Android role state alone would leave API access decisions outside the authoritative service.

Limitations

  • The source shows code and configuration boundaries, not security certification or production deployment.

Evidence

  • Spring Security configuration

    Stateless security filter chain, public auth routes, role gates, BCrypt password encoder, and method security.

    Pinned commit: 609e7f567720ec1edf186d5803fbd744e063e34b

  • JWT filter and token utilities

    Bearer extraction, active-session check, JWT validation, and role authority construction.

    Pinned commit: 609e7f567720ec1edf186d5803fbd744e063e34b

  • Account controller

    Role-guarded account creation, owner/admin reads, status operations, and transaction-history route.

    Pinned commit: 609e7f567720ec1edf186d5803fbd744e063e34b

  • KYC admin review boundary

    Admin-only case listing, decision transitions, and check inspection.

    Pinned commit: 609e7f567720ec1edf186d5803fbd744e063e34b

  • KYC file access boundary

    Owner/admin authorization before reading stored KYC bytes.

    Pinned commit: 609e7f567720ec1edf186d5803fbd744e063e34b

  • bank-app token storage

    AES/GCM token encryption, DataStore persistence, decryption, and clearing.

    Pinned commit: 770afcff097a58cfadf2be47e4c71fca301ca8ac

  • bank-app Keystore encryption

    Android Keystore AES key generation and GCM parameters used by token storage.

    Pinned commit: 770afcff097a58cfadf2be47e4c71fca301ca8ac

Use review fallback for KYC uncertaintyWhy can KYC uncertainty route to UNDER_REVIEW rather than approval?implemented

Decision

Represent non-approval failures and ML unavailability as UNDER_REVIEW unless the explicit low-score rejection branch applies.

Context

KYC combines multiple checks and an external FastAPI aggregate call; missing or unavailable signals need an explicit policy outcome.

Constraints

  • A low-score rejection branch is distinct from missing or unavailable evidence.
  • The Spring service records check and reason data and retains a reviewable case state.

Rationale

  • The source preserves a reviewable case state and records reason/check data instead of collapsing every missing or unavailable signal into a rejection or approval.

Trade-offs

  • UNDER_REVIEW preserves human reviewability but does not claim a favorable model outcome or eliminate operational follow-up.

Alternative considered

  • A binary approve/reject-only policy was not selected in the audited code path.

Limitations

  • Thresholds and policy code are not measured accuracy or false-rejection outcomes.
  • Calibration tooling is not a completed calibration study.

Evidence

  • FastAPI KYC aggregate policy

    Reason codes and APPROVE/UNDER_REVIEW/REJECT policy branches.

    Pinned commit: 7e4beb846c65afc99966a6e4edc9dfd3c9311250

  • KYC auto-review orchestrator

    Scheduled batch, bounded case claiming, file reads, FastAPI call, check persistence, decision mapping, and failure fallback.

    Pinned commit: 609e7f567720ec1edf186d5803fbd744e063e34b

  • KYC status transitions

    Explicit pending, auto-review, under-review, more-information, approved, and rejected transitions.

    Pinned commit: 609e7f567720ec1edf186d5803fbd744e063e34b

These records are a curated view over the portfolio's existing project evidence. They describe implemented or explicitly accepted boundaries, not production-readiness or outcome guarantees.