Experience & Interface
Product encounter
Interfaces and route boundaries shape how people and systems enter a product.
- Next.js App Router surfaces
- Typed UI and route code
- Explicit input boundaries
Implemented in repository
ShadowSpark / Architecture note 01
Product architecture, with the evidence left visible.
A company-wide view of interfaces, workflows, applied AI, integrations, data, and trust—without implying that every product uses every layer.
Product & applied-AI architecture
Five structural layers. One cross-cutting trust plane.
Company-wide pattern: not every product uses every layer, and source-code presence does not establish production configuration.
Application & Workflow
Product behavior
Application rules and queued workflows coordinate what the product may do.
- Route and service logic
- Deterministic workflow rules
- Queue and worker code
Implemented in repository
Applied AI & Context
Grounded intelligence
Selected product paths can retrieve context and prepare model-assisted proposals.
- Retrieval and embedding paths
- Model-client boundaries
- No implied operational authority
Implemented in repository
Platform Integrations
External capabilities
Provider boundaries connect products to services without making those services the product core.
- Payment and crawling clients
- Messaging and calendar code
- Explicit provider boundaries
Implemented in repository
Data & Infrastructure
Durable foundations
Schemas, storage, queues, and deployment configuration support product state and delivery.
- Prisma and PostgreSQL schemas
- Redis and BullMQ code
- File and cloud-storage paths
Implemented in repository
Operational Reality Flow
A model proposes. The system decides what may happen.
This is behavioral order, not another layer model. It preserves context, authority, and evidence between a request and an action.
- 01
Receive
Capture the request and the identity, channel, and policy context available to it.
- 02
Ground
Retrieve relevant material and preserve where that context came from.
- 03
Propose
Combine model output with deterministic rules without granting the model authority.
- 04
Authorize
Apply validation, access, policy, and human-review requirements before action.
- 05
Act & Record
Perform only the approved operation and leave evidence for inspection and learning.
Cross-cutting trust plane
Trust is a plane, not a checkpoint.
Trust Plane — Security, Governance & Reliability. A control example is not certification; applicable controls and operating evidence require review for each deployment.
Deployment verification required
Input trust boundary
Input is evidence, not instruction
Retrieved text and user content remain untrusted until application rules validate their use.
Access boundary
Identity does not imply authority
Authentication establishes identity; the requested operation still needs an explicit authorization decision.
Action boundary
Consequences require accountability
Consequential, customer-facing, or irreversible actions should preserve a responsible human or policy decision point.
Reliability boundary
Events are evidence, not certainty
Recorded signals support inspection, but coverage and retention must be verified in each deployment.
Architecture principles
The invariants outlast the tools.
- I
Evidence before assertion
Public language should identify whether a capability is implemented, illustrative, or deployment-dependent.
- II
Proposals before actions
Model output remains a proposal until deterministic controls and accountable authority approve its use.
- III
Boundaries before scale
Clear input, context, access, action, and operations boundaries matter before performance claims do.
- IV
Operations before guarantees
Events and health signals are foundations for inspection, not substitutes for verified operating evidence.
Design for continuity