DEV Community: Andrii Shupta

Encois: Building Organizational Intelligence on Google Cloud

Andrii Shupta — Thu, 24 Sep 2026 00:00:00 +0000

I built Encois for the All Things Agentic Hackathon to explore how an AI system can follow changing company context without becoming an unrestricted chatbot. This article explains the system design behind its event-driven control plane, durable Temporal workflows, scoped agents and evidence model, including why PostgreSQL, raw artifacts, Organization Memory and Workflow Memory have separate responsibilities.

🔗 Links

The idea

Encois is a small organizational intelligence system. The easiest way to describe the idea is a mini-Palantir for companies: it connects information from different parts of a business and helps people understand what is changing. Its read-oriented product loop is deliberately narrow: observe → correlate → explain → recommend.

A company with 50–100 people continuously produces new context. A Jira issue becomes blocked, a pull request fails its checks, a deployment goes wrong, a customer sends an important email or an internal decision changes a release plan.

Each event means little in isolation. The useful context appears when a failed check belongs to a pull request, the pull request blocks a Jira issue, the issue belongs to Friday's release and the release affects a customer commitment.

The question is:

“What changed, why does it matter, and what needs attention now?”

Why this is more than a RAG chatbot

The obvious implementation would collect company documents, put them into a vector database and add chat. Retrieval can help find relevant semantic context, but a company is a changing system rather than a static collection of documents.

Encois is therefore designed around Integrations, scoped Sources, webhooks, immutable revisions and durable Workflows. Every useful result should remain connected to real events, authorized data, user permissions, workflow history and inspectable evidence.

RAG may support retrieval, but it must not decide who can access data, whether a Workflow completed or whether an external action is allowed. Those decisions belong to deterministic application boundaries.

A release-safety example

Imagine a delivery manager asking:

“Is this release still safe to ship on Friday?”

The answer may depend on open Jira work, GitHub pull requests, failed checks, deployment events and a document containing the release requirements. An Encois Workflow can collect those signals and return three layers:

Observed facts — what Jira, GitHub and other Sources returned.
Interpretation — which blockers or dependencies were found across those facts.
Recommendation — what a person should review or decide next.

The recommendation does not hide its evidence. The user can inspect the issue, failed check, source and observation time behind it. That product requirement drives the need for provenance, freshness, identity, scope and durable execution.

Starting with system design

Encois was a hackathon project built around Google Cloud and enterprise agents. Before building most of the application, I defined where state should live, how events should enter the system, how permissions should survive a long-running Workflow and how agents should access tools. The goal was one demonstrable vertical slice without collapsing the control plane, execution engine, agent runtime and data plane into one service.

The submission also needed to demonstrate autonomous behavior beyond a chat loop. I used Source ingestion and a multi-step release investigation as that vertical slice: an event enters through a typed boundary, Temporal keeps the work durable, bounded agents collect and interpret evidence, and the Dashboard presents a reviewable result.

At article scale, the architecture is easier to read as two connected views:

The architecture documentation contains the complete deployment view with service identities, secrets, telemetry and local adapters.

The important decision was giving each part one clear responsibility rather than adding services for the sake of the diagram.

Product concepts and immutable execution

Encois separates the product into a few explicit concepts:

Integration — an organization-level connection to GitHub, Jira or another provider.
Source — a repository, project, document or other scoped provider resource.
Source Revision — an immutable version of Source data.
Template — a reviewed starting pattern for a Workflow.
Blueprint — the resolved and approved definition of its steps.
Workflow — a named process the organization can run again.
Run — one durable execution of a Workflow.
Evidence — a reference supporting a fact or conclusion.

This structure makes execution inspectable. If a Template changes tomorrow, an old Run still points to the approved Blueprint used at the time instead of silently reinterpreting history through new configuration.

Events, Sources and changing context

An organizational intelligence system cannot depend only on manual questions. Integrations connect Encois to company systems, while Sources narrow those connections to resources a team is allowed to use. Webhooks and ingestion Workflows bring new events and revisions into the platform.

Provider credentials remain references resolved through Secret Manager. Large raw artifacts belong in Cloud Storage, while PostgreSQL stores the Source, its authorized scope, immutable revision and artifact reference. Temporal receives references and execution context rather than raw documents or credentials.

The private Agent Gateway reads the artifact, normalizes it and extracts facts with provenance. Evidence preserves the provider record, observed and ingestion times, freshness, transformation version and visibility scope where available. Hosted adapters can project structured facts into Spanner Graph and distill relevant semantic context into Memory Bank. Derived memory remains useful context, but it is never stronger evidence than the event or document it came from.

Temporal as the execution source of truth

Agent work often lasts longer than one HTTP request. It can include several tools, temporary failures, retries, external events, human approval or a pause while waiting for more information.

Temporal owns the durable execution state: Workflow history, retries, timers, Signals, cancellation, recovery and state between steps. PostgreSQL stores the product-facing Run projection, evidence, actor, scope and audit data without trying to reproduce Temporal's state machine.

One Coordinator per organization

Each organization has one long-lived Coordinator Workflow. It receives versioned lifecycle events such as an Integration being connected, a Source becoming ready, a Workflow start being requested or a Run completing. Temporal Signals and Continue-As-New let it preserve coordination without growing one unbounded Workflow history.

The Gateway writes product state and an outbox event in the same PostgreSQL transaction. A dispatcher leases the row and delivers the versioned event to the Coordinator with retries. Delivery is at least once, so duplicate events are expected and deduplicated by stable event and Workflow identities. This avoids saving a Run while losing the request before Temporal receives it.

For the hackathon version, the dispatcher stays inside the Gateway API. It can later move behind Pub/Sub or Kafka without changing the event contract or creating a second workflow engine.

This also defines the consistency model shown to the user. A queued PostgreSQL Run appears as preparing before Temporal exposes the execution. After the start, Temporal owns execution status and history, while PostgreSQL stores the query-friendly projection, evidence, actor, scope and audit metadata. If either side is unavailable, the API reports stale or unavailable state instead of manufacturing agreement.

Generic Blueprint execution

The Go Runtime executes approved Blueprints through a generic Temporal Workflow. A Blueprint can contain tool steps, agent steps, deterministic transforms, dependencies, conditions, timers and approval Signals. Independent ready steps can run in parallel.

The current implementation runs one approved Google ADK Agent Definition as one Temporal Activity. Temporal can retry that bounded unit while model and tool calls remain outside deterministic Workflow code. This gives internal agent turns coarser visibility and retry behavior, a trade-off that a deeper Temporal and ADK integration could address later. A waiting Run remains durable while it waits for a timer, external condition or approval Signal; paused is a separate versioned product command.

Bounded agents and deterministic boundaries

Encois does not give one agent every tool and ask it to operate the organization. Each agent has a narrow role, typed input and output, an allowlist of tools, a timeout, retry limit, budget and organization scope.

Authentication, permissions, scope calculation, Workflow transitions, schema validation, deduplication and approval rules remain deterministic code. Google ADK and Gemini handle bounded reasoning and synthesis. The model can interpret evidence, but it cannot decide that a user belongs to another organization or that a failed Run succeeded.

The private Agent Gateway checks service identity, a short-lived signed execution capability, organization scope, actor, policy version and the requested tool. Provider credentials never enter the browser, model or Temporal history. Tool names, arguments and provider content remain untrusted until they pass registry, schema and policy checks. Tools are read-only by default; any future write to Jira, GitHub or another provider needs separate permission, approval, audit, idempotency and recovery boundaries.

A recommendation is not an automatic action.

Contracts are part of the architecture

The public Gateway is TypeScript, while the Runtime and Agent Gateway are Go. Their boundaries use versioned OpenAPI and JSON Schema contracts rather than shared source files or database models. Coordinator events, Workflow inputs, tool manifests, evidence and private service payloads are validated on both sides; unknown versions and invalid states fail closed.

The Runtime never queries the control-plane database to reconstruct missing application state. An approved Blueprint snapshot and execution context enter through Temporal, while provider-specific payloads stop at the Agent Gateway and become small typed evidence records. This keeps language and provider choices behind explicit adapters instead of turning PostgreSQL into an integration bus.

Clear ownership across Google Cloud

Each Google Cloud service has a specific responsibility:

Runtime — Cloud Run. Hosts the Dashboard, Gateway API, Agent Runtime and private Agent Gateway as independently deployable services.
Control and artifacts — Cloud SQL for PostgreSQL and Cloud Storage. PostgreSQL owns product state, permissions, Runs, outbox rows and projections; Storage owns large raw Source artifacts.
Organizational context — Spanner Graph. Stores structured company facts and relationships with provenance.
Agent context — Agent Platform Memory Bank. Stores agent-specific semantic context between Workflows without becoming the source of truth.
Reasoning — Vertex AI and Gemini. Receives validated, scoped inputs for reasoning and synthesis.
Trust and operations — Secret Manager, Cloud Logging and Cloud Trace. Protects provider credentials and records timing, retries, evidence reads and error classes.

The source-of-truth split is easier to see as state ownership:

State	Source of truth	Consumer-facing role
Identity, permissions, configuration, Runs and outbox	PostgreSQL	Gateway authorization and Dashboard projections
Workflow history, retries, waits and cancellation	Temporal	Durable execution and live Run status
Original Source payloads and large artifacts	Cloud Storage	Scoped reads through the Agent Gateway
Structured facts and relationships	Spanner Graph	Evidence-linked organizational queries
Agent-specific semantic context	Memory Bank	Scoped retrieval across related Workflows

The separation between PostgreSQL, Spanner Graph and Memory Bank is deliberate. PostgreSQL is the control plane, Spanner Graph models durable organizational facts and relationships, and Memory Bank supports agent retrieval. None of them replaces Temporal's execution history or the original Source artifact.

The current Graph integration projects scoped fact nodes with provenance. Rich entity normalization and relationship edges remain future work, which is why the article treats them as a direction rather than a finished enterprise knowledge graph.

Go was outside my main stack, but it was a practical fit for the Temporal worker and Google ADK runtime. AI helped me build the first small implementation, although learning Go properly still requires more time with the language and SDK documentation.

Observability follows the same boundaries. Request and trace IDs, organization scope, Workflow identity and Run identity travel across the Gateway, outbox, Temporal Activities and private tool requests. Structured telemetry records duration, retry count, provider, model and error class without storing raw credentials, unrestricted documents or hidden model reasoning.

Permissions must survive the Workflow

Organization is the hard tenant boundary in Encois. Inside it, access narrows through organizational units:

The Gateway calculates effective scope from the authenticated membership and selected unit. Checking permission only during the first HTTP request would be insufficient because a Workflow can continue long after that request ends.

The same organization, actor, authorized unit IDs and capability travel through the outbox, Temporal Workflow and private tool requests. The Runtime and Agent Gateway verify them again at their own boundaries. A model-generated organization ID never becomes authorization simply because it appeared in a payload.

The system also fails closed. Missing onboarding data is an error, an unknown Run status is a contract mismatch and provider authentication failure remains visible as degraded or requiring reauthorization.

Turning the dashboard into an operational view

The first Dashboard exposed Integrations, Sources, Templates, Blueprints, Workflows, Runs, events, permissions and memory. That was useful for validating the backend and demonstrating that the control plane was real, but it also made the product feel like an interface to the database.

After testing that version, I shifted the UI toward one operational view that answers a smaller set of questions: what changed, what needs attention, which release is blocked, what has already been checked and which conclusion still needs a human decision.

The underlying control-plane screens remain necessary for configuration and debugging. They should support the intelligence experience rather than become its main interface.

Current limits and next steps

The local environment keeps the same application topology with Docker Compose, PostgreSQL, Temporal, Auth and Storage emulators, the Dashboard, Gateway, Runtime and Agent Gateway. It seeds a synthetic company called Sun Inc with real control-plane records and Temporal-backed Runs; provider fixtures and infrastructure mocks remain explicit adapter modes.

Real Gemini, Spanner Graph and Memory Bank integrations are opt-in because they require configured Google Cloud resources and may incur cost.

The hackathon MVP still needs:

richer Graph entities and relationships;
production validation of hosted IAM, retention and cost;
full organization-unit isolation in the hosted Memory Bank adapter;
hardened provider authorization and lifecycle behavior;
independent outbox delivery at larger scale;
more granular Temporal and ADK execution;
stronger deployment and disaster-recovery processes.

The next product step is a smaller and more useful operational picture. Scheduled briefings and change detection could surface investigations before a user asks, while conversational or voice interfaces could help explore evidence without replacing identity, scope and audit boundaries.

Agents may later propose Sources, Blueprints or Workflow configurations, but those proposals should remain reviewable. External actions need stronger approval and recovery guarantees than recommendations.

Summary

Encois explores organizational AI as an event-driven system rather than a chatbot over documents. Its design separates product state, durable execution, raw evidence, structured organizational facts, agent memory and model reasoning so each layer has one clear source of truth.

Temporal makes long-running agent work recoverable. Google Cloud provides explicit boundaries for services, artifacts, secrets, organizational context and model execution. Signed scope and capabilities preserve authorization after the original browser request has ended, while evidence keeps facts, interpretations and recommendations distinguishable.

The main product direction is equally clear: users need one operational view of what changed and what deserves attention, with the architecture underneath making every result scoped, durable and inspectable.

MiyKo: A Durable AI Workflow for Shared Shopping

Andrii Shupta — Wed, 23 Sep 2026 00:00:00 +0000

🔗 Links

I built MiyKo for the AI Factory by Silpo hackathon to test a harder version of AI shopping: one order shared by several people over time. The result connects a React Native app, a role-aware API, a durable LangGraph workflow, Mem0 memory and Silpo’s real basket. This article explains the system boundaries that made the shared order work, where human approval stays in control, and what would need to change before production.

The idea

Silpo already has an AI assistant that can find products and help with a basket. I wanted to see what changes when the unit of work is a shared order , rather than one prompt from one person.

A shared order can outlive the first chat: one person starts dinner planning, another adds drinks, a child requests ice cream, an owner approves it, and the basket is prepared hours later. That makes identity, permissions, durable state and current provider data first-class parts of the design.

Why a shared order changes the product

A group can be a family, flatmates, coworkers planning lunch or friends organizing a picnic. The same flow also works for one person.

Imagine a simple dinner:

Mom starts the order.
Dad adds drinks.
A child asks for ice cream.
The child’s request waits for approval.
The family confirms the plan.
MiyKo prepares the real store basket.

Everyone works with the same workflow, but not everyone has the same permissions.

In the MVP, an owner or admin can approve requests and perform provider actions. An editor can add to the shared plan. A viewer can make a request, but it must be approved before it affects the real basket.

This is important because the AI does not decide who has authority. The API knows the authenticated member and their role. A prompt cannot turn a viewer into an owner.

Keeping the architecture small

Silpo was the real provider used for the hackathon. The provider boundary keeps the shared-order design independent of that particular store.

MiyKo has five main runtime boundaries:

Expo / React Native for the mobile experience;
Hono API for authentication, group roles and provider connections;
LangGraph for the active workflow and pause/resume state;
Mem0 for long-term group and member memory;
Silpo MCP for current products, basket operations, fulfillment and checkout.

The complete request path looks like this:

The API is the security boundary. LangGraph owns the order state and pause/resume transitions. LangChain provides the model and tool integration inside that graph; Mem0 supplies long-term context when needed. The model proposes a next step, while the API checks the authenticated actor and permissions before protected actions. When that step needs store data or a basket change, it calls Silpo through MCP. The result returns to LangGraph, is saved in the workflow state and becomes the next status shown in the app.

PostgreSQL is a small control plane and records the outbox events that bridge API commands to the workflow. It stores users, groups, roles, provider bindings, workflow references, approval decisions, audit records and outbox state. Each order has one workflow UUID, reused as its LangGraph thread ID, so later actions resume the same process. The outbox worker retries temporary delivery failures with an idempotency key; an owner’s decision to decline a request remains final.

It does not store a second product catalog, a second basket or a copy of LangGraph checkpoints. This keeps a single source of truth for each kind of data.

This was an important decision. Creating tables for everything would make the system look complete, but it would also create difficult questions:

Which price is correct when Silpo changes it?
What happens when a locally stored product becomes unavailable?
Which copy of the basket is the source of truth?
How do two workflow states stay synchronized?

The simpler answer is to leave provider data with the provider, workflow state with LangGraph and reusable memory with Mem0.

The complete MiyKo flow

The demo follows one shared order from the first request to the Silpo checkout.

1. One workflow keeps the process together

The MVP uses one workflow kind called step-order. LangGraph keeps the active state, pauses when a decision is needed and resumes the same workflow later.

This graph is not only a chain of AI calls. It represents the order lifecycle: planning, member changes, approvals, provider actions and completion. The screenshot shows the graph in Studio. LangGraph runs the workflow; LangSmith provides development and tracing tools around it.

2. Different people see the same order

Each group member has a separate authenticated session. They do not share login credentials, but they can see the same active workflow.

The group view shows members, roles and the connected provider. The owner connects Silpo once for the group through OAuth 2.1 with PKCE; MiyKo never asks for the store password.

Other members can use that connection through the workflow, but they never receive the provider token.

3. Silpo stays a separate trusted system

The credentials remain encrypted on the backend. When the workflow calls Silpo MCP, the API supplies the access token as runtime-only context. The mobile app, LangGraph state and Mem0 do not hold that token.

4. Previous purchases become useful memory

Before starting the first order, the owner can import a summary of recent Silpo receipts.

This gives MiyKo context such as products the group bought before or choices that may be useful again.

Memory helps the agent make a better suggestion. It does not give permissions and it does not replace the current provider data.

5. The plan exists before the real basket

The owner starts a dinner workflow in the React Native app. MiyKo reads relevant memory and creates the initial shared plan. At this point, the Silpo basket is still untouched. The screens below show the progression from an initial plan to a prepared basket; the provider action happens only after the group confirms the plan.

I wanted planning and execution to be separate. During planning, people can speak naturally, add ideas and change their minds. Before execution, the system must check the actor, permissions and current provider state.

6. The workflow pauses for approval

When a viewer asks to add ice cream, the request remains in the same workflow and waits for an owner or admin.

After approval, LangGraph resumes the same thread. The context is not copied into a new chat and the order is not recreated from scratch.

7. The agent prepares a real basket

Only after the group agrees on the plan does an authorized member ask MiyKo to prepare the basket.

The workflow discovers the current Silpo MCP tools, resolves products and updates the real provider basket. Product names, images, prices and totals come from Silpo, not from a local MiyKo catalog.

8. Checkout still belongs to Silpo

Silpo MCP can work with the basket and return a checkout link, but it does not expose a final place-order tool. MiyKo prepares the basket; the owner finishes the purchase in Silpo.

That boundary is intentional. MiyKo must not say that an order is complete when it only has a basket and a checkout URL.

The screenshot shows a completed MiyKo workflow. The final provider confirmation still happens in Silpo.

Memory, not chat history

I was not interested in storing a long chat transcript and calling it memory.

I wanted memory to be managed:

add useful memories;
update them when preferences change;
remove them when they are wrong or no longer relevant;
keep shared group memory;
keep personal member context;
keep order-specific state inside the active workflow.

These are different things.

Mem0 stores long-term group and member memory. LangGraph keeps the transient context for the current order. PostgreSQL does not duplicate either one.

For example, “the group often buys food for two days” can be long-term memory. “Add ice cream to tonight’s order” belongs to the active workflow. The current ice cream price still belongs to Silpo.

This separation also protects the permission model. Memory may say that a child likes ice cream, but it cannot approve the purchase. The API still checks the real member role.

Reworking the app UI

The first version of the React Native UI came from a simpler model. It worked, but the screens were confusing. I opened the app, walked through the order flow, and tested where the experience broke down before redesigning it.

That gave me specific problems to fix: which person is acting, which request is waiting for approval, whether the basket is still a plan or already prepared, and what the next action should be. Once the flow made sense, I rebuilt the screens around those states. Seeing and testing the real interface was more useful than asking a model for a polished screen in one prompt.

Summary

MiyKo’s design starts with a shared order that can continue across people and time. The API verifies identity and permissions; LangGraph keeps the order resumable; Mem0 supplies reusable context; and the provider remains the source of truth for products, prices and checkout. Keeping these responsibilities separate prevents a remembered preference or a model suggestion from becoming an unauthorized action.

The same separation shaped the app: people need to see whether they are planning, waiting for approval or acting on a real basket. Testing the first interface exposed those gaps before the redesign. Silpo supplied the concrete integration for this project, but the useful result is the architecture and interaction model for coordinating a group around an external action.

I Built a Fasting App I'd Actually Use. Apple Rejected It.

Andrii Shupta — Tue, 22 Sep 2026 00:00:00 +0000

🔗 Links

Apple rejected Simple Fasting under Guideline 4.3(a), “Design – Spam.” I had spent roughly two to three weeks building and polishing the app, perhaps closer to a month in total. Then I waited about a month for the first review. I replied to explain the app, but the rejection stood.

The message said the app shared a similar “binary, metadata, and/or concept” with apps from other developers, with only minor differences. It did not say which of those was decisive.

I still use Simple Fasting. It is installed on my phone through TestFlight, and I am happy with the app I made. Of course, I would rather have it publicly available in the App Store. For now, I can use it myself even though the release was rejected.

I built it myself with Expo and React Native; I did not repackage someone else's app. But I cannot pretend that a fasting tracker is a new concept. What felt different to me was the experience I wanted to use every day. That is where this story starts.

The app I wanted to use

I used fasting apps that began simply and grew into something more demanding. With Zero, what frustrated me most was opening the app to start or stop a fast and running into a paywall. Sometimes I had to wait for a close button to appear. At times I could not dismiss it and ended up closing the app entirely. I do not know whether that was a bug or an intended flow, but I knew I did not want that experience in my own tracker.

My idea was small: open the app, start or stop a fast, and close it. No account, analytics, or subscription popup interrupting that action. Fasting history, goals, notes, and reminders would stay on the device unless the user chose to export them. Privacy was part of the product, not a feature to add later.

Simple Fasting grew beyond a timer. It has local history and statistics, reusable goals, reminders, import and export, iOS and Android widgets, an optional iOS Live Activity, and a small website. But the main interaction still needed to feel calm and immediate.

That constraint helped me decide what belonged in the first screen. The timer and its main action needed to be obvious. History and statistics could be there when I wanted them, without asking for attention every time I opened the app. I was willing to build more behind the scenes if it made the everyday interaction feel smaller.

Building it with AI, without giving up the decisions

I am a software engineer, and I used AI agents across product planning, architecture, React Native code, tests, UI iterations, documentation, and release work. That made implementation faster. It did not decide what the product should be or whether a screen felt right to use.

Before building many features, I wrote down the product goal, privacy boundary, data behavior, and non-goals. This gave each new AI task the same starting point. If I asked for “a modern fasting app” without those boundaries, an agent might reasonably add authentication, cloud sync, or subscriptions. Those are common choices, but they were wrong for this app.

I did not call it spec-driven development at first. I just wanted decisions to survive beyond one chat. An agent could complete a task well and still lose context before the next one. Written rules made it easier to catch a feature that worked technically but moved the product away from what I wanted.

The repository contains the Expo app, a static Astro website, and shared help and legal content. The app's local history is the source of truth for statistics. Widgets and the Live Activity need to reflect the same active fast as the app. When several agents work on connected surfaces, clear ownership matters more than another long prompt.

My usual loop was simple:

describe one outcome → implement it → run the app → use it → explain what feels wrong → adjust it

For example, “add an end-of-fast reminder” was not enough. The task needed to specify that the reminder is local, belongs to the active fast, changes when that fast changes, and never blocks the timer if notification permission is denied. AI could help build it once those product rules were clear.

I also changed the amount of reasoning I used for different tasks. A narrow component or test did not need the same effort as a decision about storage or native behavior. What mattered was giving the task enough context and checking the result. A model's confident explanation was never evidence that the feature worked on a device.

Where faster coding made the app heavier

AI makes another safety path feel cheap. I added retries, reset flows, and recovery behavior while the core product still needed real use. Some safeguards were justified: local data has no backend copy, and import and export give people control over it. Other paths created more states, warnings, tests, and maintenance than the first version needed.

I learned to ask which real failure a feature handles before adding it. The cost of generating code is small; the cost of living with every extra state is not.

This was especially tempting because the app kept expanding. A timer led to goals; goals led to reminders; sessions led to History and statistics. Each feature sounded modest on its own. Together they changed the number of ways the app could behave. If I were starting again, I would finish and use the central fasting flow longer before building so much recovery logic around it.

I also delayed the design system. Early screens looked fine individually, but spacing, controls, and screen structure began to drift. I paused feature work for about two days to make shared components, theme tokens, and clearer visual rules. After that, I could ask an agent to reuse an existing section or button instead of describing its appearance from scratch.

A design system gave the app consistency. It also made the AI work more precise. But it could not replace opening the product and seeing what happened on a real screen.

The cleanup was not an attempt to make every screen identical. It gave repeated elements a common shape and let the differences serve the task. I still adjusted screens after seeing them in context, especially where native navigation and safe areas affected the layout.

The screen had the final say

Wireframes and specifications helped me choose a direction, but I made the final UI decisions by using the app. The iOS Simulator and Android emulator exposed content hidden by navigation, awkward scrolling, keyboard overlap, picker behavior, and differences between light and dark themes. A screenshot could show spacing; it could not show whether a selected goal survived reopening a tab.

Specific feedback worked best. “This screen feels wrong” gave an agent little to act on. “The Start button is hidden behind the tab bar on a small iPhone” described a state, an action, and a visible failure.

I did focused checks during iteration, then ran broader tests and builds once a feature was stable. Physical-device checks still mattered for notifications, widgets, and Live Activity. A successful build proved that the project built; it did not prove that the interaction was good.

The most useful unit of work was a complete user flow. Choosing a goal, starting a fast, updating the widget, ending the session, and seeing it in History all depend on the same data. Building each screen in isolation could leave several incompatible versions of one fast.

That is also why I did not treat a simulator screenshot as a release check. I could inspect the layout quickly there, while a native build and a physical device answered different questions. Notifications and widgets needed those later checks. The faster UI loop helped me make decisions sooner, but the broader checks still had to happen before submission.

What I take from this

The rejection did not tell me that the code was copied or that Expo was the problem. Apple's wording included binary, metadata, and/or concept. I know how I built the app; I do not know which similarity mattered most to the reviewer.

My best guess is that the concept mattered most: Simple Fasting is another tracker in a crowded category. I knew other fasting apps existed. I just thought that if I wanted a version without an obstructive paywall, I could build and submit my own. I did not expect an established idea itself to be a reason for rejection, especially when many similar apps are already in the store.

Privacy, a clean UI, and no paywall in the core flow are meaningful differences for me. They may be too subtle to distinguish the app during review. I wonder whether clearer positioning, or a more visible feature of my own, would have helped. I cannot know that, or whether marketing or the developer's size played any role. Next time, I would find a distinctive product behavior early, even if the idea first sounds a little odd, and make its value obvious before spending weeks polishing the implementation.

After the rejection, I made the previously private repository public so people could inspect the work behind Simple Fasting. I still like the app I built, and I would still use it. The experience taught me two things at once: AI is useful when I keep the product decisions and verify the result, and good engineering does not guarantee a place in the App Store.

I have not turned this into a story about beating App Review. For now, the honest ending is that I made something useful to me, learned a great deal from building it, and could not publish it there. Showing the work publicly feels more useful than pretending the rejection did not happen.

Directing a 3D Web Experience with AI

Andrii Shupta — Mon, 21 Sep 2026 00:00:00 +0000

🔗 Links

The same opening scene in dark and light themes.

The idea

I built Cathedral of Threads for a small GSAP and Webflow challenge.

The idea was to create a one-page 3D experience inspired by the Coordinate from Attack on Titan: a strange place outside normal time, with a huge tree, paths that feel like human memories, and a transition between night and day.

The page is controlled by scroll. As you move down, the camera moves through the scene. The environment changes, the tree gets closer, and the story moves through several short chapters.

I wanted it to feel more like a small digital artwork than a normal landing page.

I used Astro for the website, GSAP for the scroll and animation, Three.js for the 3D scene, and Webflow mainly for deployment through its CLI. Most of the scene, animation, and interaction code was created through conversations with AI coding agents.

The unusual part is that I did not know Three.js well when I started.

I started from the result, not the code

I set up Astro, added GSAP, and prepared the project for Webflow. After that, I worked with the agent on the main experience.

At first, I barely looked at the generated Three.js code.

This may sound careless, but reading unfamiliar 3D code was not the best way for me to judge the result. I could see camera coordinates, curves, materials, lights, particles, and many numbers, but that did not tell me whether the scene felt right.

So my main feedback loop was visual:

Ask the agent to make one change.
Open the page.
Scroll through the full scene.
Decide what feels wrong.
Explain the problem more clearly.
Repeat.

I added image references and described the composition I wanted. I explained where the tree should be, how large it should feel, how close the camera should move, which elements should stay in the background, and how the scene should change between night and day.

The agents wrote most of the code. I directed the result.

That sounds simple, but most of the work was hidden inside the last step: explaining exactly what “looks right” means.

Technically correct can still look wrong

AI can generate a valid Three.js scene very quickly. It can create a renderer, camera, lights, materials, geometry, particles, and animation. The page can load without errors and still look bad.

I saw this many times during the project.

The tree existed, but it looked too small. The paths were animated, but they did not create depth. The camera moved, but it did not feel cinematic. The bloom worked, but it made the whole image flat. The transition between dark and light was technically there, but it did not feel like part of the story.

These were not problems that a build command could find.

I had to turn visual reactions into more useful instructions:

“Make it more cinematic” became “keep the camera low during the approach, then tilt upward near the tree.”
“The scene feels empty” became “add more paths close to the camera, but keep the centre readable.”
“The tree is weak” became “show its full silhouette in the first frame and make the branches denser near the top.”
“The light mode does not work” became “change the world gradually during the journey instead of switching colours at one point.”

The more specific my feedback became, the better the agent became at changing the right part of the scene.

Why Three.js was difficult to review

Normal UI code is easier for me to connect with the result. I understand what a button, grid, breakpoint, or CSS property should do. If something is wrong, I usually know where to look.

Three.js was different.

A visual result can depend on camera position, field of view, geometry, material, lighting, fog, post-processing, and the relationship between all of them. One small change can make the whole scene feel different.

The maths also makes code review harder when you do not know the library. Looking at a group of vectors and curves does not immediately tell you what the camera journey will feel like.

Because of that, I learned Three.js from the problems I actually had.

I did not try to study the complete library before building. I learned what a renderer owns, how a scene and camera work, how geometry and materials are connected, why a render loop should stay under one owner, and why resources need to be cleaned up.

That was enough to start checking the agent's decisions instead of only checking the final image.

This was the point where the project changed from “AI generated this” to “I can explain why it is built this way.”

What Astro, GSAP, and Three.js each did

Keeping the responsibilities simple helped me understand the project.

Astro owned the page structure, HTML content, and the split between desktop and mobile experiences.

Three.js owned the canvas: the camera, terrain, tree, memory paths, particles, lighting, fog, and rendering.

GSAP connected the scene to the visitor. One main scroll timeline changed camera movement, light, scene state, text, and progress as the user moved through the page.

Webflow was mostly the deployment target. I was not using Webflow Designer to build the visual scene.

This separation was important. GSAP changed values, but Three.js still owned the render loop. Astro rendered the real HTML story, but did not try to create the WebGL scene on the server.

Once I understood those boundaries, I could give the agent better instructions and notice when a change mixed too many responsibilities.

Performance became a visual problem

The first versions of the scene had too few lines and objects. The world looked empty and the central structure did not feel large enough.

I kept asking for more: more paths, more waves, more detail, more particles, and a more complex silhouette.

It worked visually until the page started to lag.

This was the moment when I had to stop asking only for visual density and start thinking about what the camera could actually see.

The scene did not need the same amount of detail everywhere. Objects close to the camera needed more detail because the visitor could see them. Distant objects could be simpler. Anything outside the useful view should not consume the same amount of work as the centre of the composition.

The optimisation direction became:

use less detail in the distance;
keep more detail near the camera;
avoid rendering work that does not affect the visible frame;
reuse geometry and materials where possible;
do not create new objects during every frame;
cap rendering resolution instead of following the full device pixel ratio;
design complexity around the camera path.

The last point was the most useful. This was not a free camera in a game. I knew where the visitor would be looking during every part of the scroll. The scene could spend its detail where it mattered.

Performance was not separate from art direction. It changed how the artwork had to be composed.

Mobile needed a different answer

Trying to keep the full desktop scene on phones would have created more performance problems and a worse experience.

Instead, I made mobile a separate 2D passage. It uses a fixed image selected for the device theme, normal page scrolling, and real HTML text. It keeps the same idea and mood without loading the desktop Three.js experience.

This was another useful lesson: AI often tries to reuse one implementation everywhere because it looks cleaner in code. Sometimes the better product has two simpler paths.

What I had to give the agent

The agent needed more than prompts.

I gave it a product brief with the scene, story beats, interaction, visual direction, mobile behaviour, and things that were out of scope. I kept technical rules in the repository: one renderer, one animation loop, a limited pixel ratio, reduced-motion support, cleanup, and no Three.js on mobile.

I also gave it references and continuous visual feedback.

The useful input was a combination of:

the idea and mood;
reference images;
a clear description of the camera journey;
boundaries between Astro, GSAP, and Three.js;
official documentation;
performance and accessibility rules;
feedback from the real page after every meaningful change.

Without this context, the agent could still generate code. It just could not know which result I wanted.

What I learned

AI lets you start with a technology before you know it deeply. Switching models could change how quickly I reached a useful direction, but no model removed the need to judge the output. That is real, and it is useful.

But it does not remove the cost of not knowing the technology.

You pay for that gap through more iterations, more explanations, more tokens, and more wrong directions. If UI or art direction is critical, you either need to know the tool or be ready to spend time teaching both yourself and the agent what the result should be.

The agent can make a scene work. It cannot know where my line is between “technically correct” and “visually right.”

My role was not to type every line of code. My role was to keep the idea clear, judge the result, turn visual problems into specific instructions, and gradually learn enough to review the important technical decisions.

That is the main thing I took from this project.

You do not need to understand everything before you begin. But you still need to look, question, test, and learn. AI can shorten the path between an idea and a working result. It does not decide what the result should feel like.

Single Flight in Gleam: Managing Processes with OTP

Andrii Shupta — Sun, 20 Sep 2026 00:00:00 +0000

🔗 Links

The idea

I wanted to play with Gleam processes and OTP by building something more involved than a basic server. Single flight was a good fit: small enough to understand, but rich enough to explore actors, monitoring, supervision, retries, caching, and Erlang's “let it crash” approach.

If 1,000 requests ask for the same expensive resource at the same time, the application should not make 1,000 identical calls. The first caller starts the work. Everyone else with the same operation and key joins it; synchronous callers receive the same outcome.

1,000 concurrent calls with the same operation and key
                    ↓
             one callback execution
                    ↓
  1,000 call(...) callers receive the same outcome

This is not quite caching. A cache reuses completed work; single flight joins work that is still running. Different keys can still run concurrently, and two different operations do not collide even if they produce the same string key.

I built SingleFlight as a typed Gleam library for one BEAM node. The public API is small; most of the project is about deciding which process owns each piece of state and what happens when a process dies.

A complete example

This is the smallest end-to-end shape, adapted from the tests:


type Operations {
  Operations(
    get_user: single_flight.OperationDefinition(Int, String),
  )
}

pub fn main() -> Nil {
  let operations =
    Operations(
      get_user: single_flight.operation(
        key: int.to_string,
        run: fn(user_id) { "user-" <> int.to_string(user_id) },
      ),
    )

  let assert Ok(instance) =
    single_flight.new()
    |> single_flight.with_operations(operations)
    |> single_flight.start

  let assert Ok("user-7") =
    instance
    |> single_flight.use_operation(fn(operations) { operations.get_user })
    |> single_flight.call(7)

  Nil
}

Concurrent calls to get_user with 7 join one flight. A call with another user id gets a separate flight and can run at the same time.

The BEAM mental model

BEAM processes do not share mutable state. Each process owns its state and receives messages through a mailbox. That changed the design question from “which lock protects this object?” to “which process owns this state?”:

Process	Responsibility
Coordinator	Owns the map of active and cached keys.
Flight actor	Owns one key, its waiters, attempts, and retained result.
Callback worker	Runs one attempt of user code.
Supervisors	Own the runtime infrastructure and flight lifecycles.

Gleam exposes these Erlang/OTP concepts through typed APIs. A process.Subject(Message) is a typed address, an actor is a process with state and a message loop, a monitor reports process death as a message, and a supervisor defines recovery boundaries.

Why operations live in an application record

The shape of the API came from one requirement: selecting an operation must preserve its exact parameter and result types all the way to call and send.

A regular List or Dict is homogeneous, so a straightforward runtime registry would either require every operation to share the same parameter and result types or erase them behind Dynamic and cast later. Neither option gives the call site the contract I wanted.

Instead, the application defines a record that acts like a typed operation interface:

type Operations {
  Operations(
    get_user: single_flight.OperationDefinition(Int, String),
    get_report: single_flight.OperationDefinition(Nil, Int),
  )
}

Each field has its own OperationDefinition(param, result). It binds together:

the parameter accepted by both key and run;
the result returned by run;
a private identity used to scope concurrent work.

The implementation is correspondingly small:

pub opaque type SingleFlight(operations) {
  SingleFlight(config: Config, operations: operations)
}

pub opaque type OperationDefinition(param, result) {
  OperationDefinition(
    id: reference.Reference,
    key: fn(param) -> String,
    run: fn(param) -> result,
  )
}

pub opaque type Operation(param, result) {
  Operation(
    id: reference.Reference,
    coordinator_name: coordinator.Name,
    flight_supervisor_name: flight_supervisor.Name,
    key: fn(param) -> String,
    run: fn(param) -> result,
    settings: settings.Settings,
  )
}

pub fn operation(
  key key: fn(param) -> String,
  run run: fn(param) -> result,
) -> OperationDefinition(param, result) {
  OperationDefinition(id: reference.new(), key:, run:)
}

The definition is opaque and process-free; creating one does not start an actor. The fields may have unrelated types: get_user is Int → String, while get_report is Nil → Int. The record gives them source-level names without forcing a common result type or storing application values as Dynamic.

The runtime itself carries the record type as SingleFlight(operations). use_operation accepts a selector from that exact record and returns Operation(param, result):

let get_user =
  instance
  |> single_flight.use_operation(fn(operations) { operations.get_user })

let result = single_flight.call(get_user, 7)

The selector is the important part. When it returns operations.get_user, Gleam infers both Int and String. The bound operation then makes call accept only an Int and return Result(String, single_flight/error.Error); no string operation name or result cast is involved.

The public implementation shows that type flow directly:

pub fn use_operation(
  instance instance: SingleFlight(operations),
  using select: fn(operations) -> OperationDefinition(param, result),
) -> Operation(param, result) {
  let SingleFlight(config:, operations:) = instance
  let OperationDefinition(id:, key:, run:) = select(operations)

  Operation(
    id:,
    coordinator_name: config.coordinator_name,
    flight_supervisor_name: config.flight_supervisor_name,
    key:,
    run:,
    settings: config.settings,
  )
}

pub fn call(
  operation operation: Operation(param, result),
  with param: param,
) -> Result(result, error.Error) {
  call_resolved(operation, param, operation.settings)
}

Operation definitions should be created once and reused. Each call to single_flight.operation also creates a new internal reference, so recreating an otherwise identical definition creates a separate namespace.

The key defines equivalent work

The key function defines when two calls may share one result:

single_flight.operation(
  key: fn(user_id) { "github:user:" <> int.to_string(user_id) },
  run: github.get_user,
)

If the key omits a relevant input, unrelated requests may be collapsed. If it includes irrelevant changing data, useful deduplication is lost.

Internally, the coordinator scopes the string key by the operation's private reference:

type ScopedKey =
  #(reference.Reference, String)

That is why two operations can both produce "same-key" without sharing a flight or even sharing a result type.

The process topology

The runtime has two long-lived children and one temporary actor for every active or retained key:

                    OneForAll supervisor
                    / \
       FlightFactorySupervisor Coordinator
                 | |
          temporary children scoped key → flight
                 |
             FlightActor
                 |
       monitored callback worker

Within that tree, one acquisition flows like this:

caller
  │ Acquire(operation id, key)
  ▼
Coordinator
  ├─ missing key → start a FlightActor
  └─ existing key → deliver another Run message
                              │
                              ▼
                         FlightActor
                          ├─ first Run → start one worker
                          └─ later Run → add a waiter

The coordinator

The coordinator owns routing state, not user work. Its mailbox serializes Acquire, settlement, expiry, and child-down messages. That is the atomicity boundary: two callers cannot both observe a missing scoped key and create two owners for it.

Its actor message loop stays small and delegates each state transition:

fn handle_message(
  state state: State,
  message message: protocol.CoordinatorMessage,
) {
  case message {
    protocol.Acquire(key, operation_id, start, deliver, reply_to) ->
      handle_acquire(state, key, operation_id, start, deliver, reply_to)

    protocol.Settled(key, operation_id, pid, retention) ->
      handle_settled(state, key, operation_id, pid, retention)

    protocol.Expire(key, operation_id, pid) ->
      handle_expire(state, key, operation_id, pid)

    protocol.ChildDown(down) -> handle_child_down(state, down)
  }
  |> actor.continue
}

The central acquisition branch is regular actor state handling:

case dict.get(state.entries, scoped_key) {
  Error(Nil) -> start_flight(state, scoped_key, start, deliver, reply_to)

  Ok(entry) -> {
    let protocol.FlightHandle(pid:, ..) = entry.handle

    case process.is_alive(pid) {
      False ->
        state
        |> remove_entry(scoped_key)
        |> start_flight(scoped_key, start, deliver, reply_to)

      True ->
        case deliver(pid) {
          Ok(Nil) -> {
            process.send(reply_to, Ok(pid))
            touch_entry(state, scoped_key, entry)
          }
          Error(error.FlightUnavailable) -> {
            stop(entry.handle)
            state
            |> remove_entry(scoped_key)
            |> start_flight(scoped_key, start, deliver, reply_to)
          }
          Error(delivery_error) -> {
            process.send(reply_to, Error(delivery_error))
            state
          }
        }
    }
  }
}

On a miss, start_flight enforces the active-flight limit and asks the factory supervisor to start a child. On a hit, the coordinator sends the new waiter to the existing flight. touch_entry updates LRU order when that entry is cached.

Checking is_alive is not enough by itself: the process can die before accepting Run. Delivery therefore waits for an acknowledgement from the flight. If it returns FlightUnavailable, the coordinator removes the stale entry and retries acquisition with a fresh flight.

The coordinator also monitors every flight actor and removes its scoped entry when that child exits.

The flight supervisor

The factory supervisor has a smaller job: start and own flight actors. Its complete child configuration is short:

pub fn supervised(name name: Name) {
  factory_supervisor.worker_child(fn(start_child) { start_child() })
  |> factory_supervisor.named(name)
  |> factory_supervisor.restart_strategy(supervision.Temporary)
  |> factory_supervisor.supervised
}

Temporary is essential. A flight contains callbacks, waiters, attempts, and timers for one scoped key. Restarting it with empty state would not recover that work, so a crashed flight is removed and a later acquisition creates a new one.

Four invariants keep the design understandable:

Only the coordinator assigns a scoped key to a flight.
One flight owns all attempts, waiters, and the retained result for that key.
User code runs in a separate worker, never inside the coordinator or flight actor.
Coordinator messages that remove or expire an entry must still refer to the same flight pid.

The last check matters because monitor notifications and expiry timers may arrive after a replacement flight has claimed the same logical key.

One flight is a state machine

State	Event	Effect
`Idle`	First `Run`	Start one monitored worker and timeout timer.
`Running`	Another `Run`	Add a waiter without starting more work.
`Running`	Result	Ask the coordinator whether to retain or drop it.
`Running`	Crash or timeout	Retry, or settle one shared error.
`RetryPending`	Retry timer	Start the next attempt.
Finalizing	`Retained` or `Stop`	Reply to waiters, then keep or stop the actor.
Completed	Another `Run`	Return the retained outcome immediately.

Every attempt gets an id. Completion, timeout, and retry messages are accepted only when their id matches the current attempt, so a late message cannot settle newer work.

The finalizing handshake is also deliberate. The flight waits until the coordinator has registered the retained entry or removed the dropped one before replying to callers. A new acquisition therefore cannot arrive while the result is published but key ownership is undecided.

Monitoring, linking, and “let it crash”

User callbacks run in unlinked processes:

let worker =
  process.spawn_unlinked(fn() {
    let result = operation()
    process.send(state.subject, OperationCompleted(id:, result:))
  })

let monitor = process.monitor(worker)
let timer =
  process.send_after(state.subject, timeout, OperationTimedOut(id:))

This is where “let it crash” becomes a design tool rather than a slogan. A broken callback is allowed to die, but its failure is contained. Because the worker is not linked to the flight, it cannot take the waiter-owning actor down with it. The monitor turns the death into a WorkerDown message, which the flight can handle as OperationFailed or retry.

There are three outcomes:

completion: cancel the timer and settle the result;
crash: cancel the timer and handle OperationFailed;
timeout: stop monitoring, kill the worker, and handle Timeout.

The ownership boundary matters more than whether a process crashes: unsafe user code is disposable, while the process coordinating callers stays alive long enough to give them one shared outcome.

Retries belong to the flight

Retries cannot belong to individual callers. If five waiters retried independently, the implementation would stop being single flight. One flight owns one attempt sequence:

let retrying =
  settings.new()
  |> settings.retry(
    max_retries: 2,
    delay: 100,
    on: settings.FailuresAndTimeouts,
  )
  |> single_flight.operation_settings(instance)

max_retries: 2 means at most three attempts including the first. Retries may target worker failures, timeouts, or both. All waiters remain attached to the same flight. A successful value is sent to all of them; a final runtime error is delivered only to checked waiters created by call.

This does not guarantee exactly-once execution. A callback can complete an external side effect and then crash, or time out while external work continues. Side-effecting callbacks still need idempotency.

Supervision and recovery boundaries

The coordinator and the factory supervisor run under OneForAll:

static_supervisor.new(static_supervisor.OneForAll)
|> static_supervisor.add(flight_supervisor.supervised(
  config.flight_supervisor_name,
))
|> static_supervisor.add(coordinator.supervised(
  config.coordinator_name,
  config.flight_supervisor_name,
  config.settings,
))

They form one consistency boundary. If only the coordinator restarted, it would forget live flights. If only the flight supervisor restarted, the coordinator could retain dead entries. Restarting both restores a consistent empty runtime.

Together with the Temporary flight policy shown earlier, this gives a clear recovery boundary: durable infrastructure restarts together, while disposable keyed work is recreated only when a caller asks for it again.

An application with its own supervision tree can use supervised and connect after the parent has started the returned child specification:

let assert Ok(#(pending, single_flight_child)) =
  single_flight.new()
  |> single_flight.with_operations(operations)
  |> single_flight.supervised

let assert Ok(_) =
  static_supervisor.new(static_supervisor.OneForOne)
  |> static_supervisor.add(single_flight_child)
  |> static_supervisor.start

let assert Ok(instance) = single_flight.connect(pending)

`call` and `send`

call waits forResult(result, single_flight/error.Error). It monitors the flight while waiting, so a dead flight becomes FlightUnavailable instead of an endless receive.

send accepts a subject and returns after the caller has joined the flight. The subject receives successful values only; runtime errors are not delivered to it. Use call when the caller must observe failures such as Timeout or TooManyWaiters.

The library treats an application's own Result as an ordinary successful value. If a callback returns Result(User, ApiError), SingleFlight errors still describe only the runtime around that callback.

The first caller for a scoped key also defines that flight's callback and operation settings. Later callers join the active flight; they do not replace its retry, cache, timeout, or waiter policy.

Each synchronous caller still has its own receive deadline. A caller may return Timeout while a longer shared flight continues for other waiters. Version 1 has no caller cancellation, so its reply subject remains attached until that flight settles.

Caching without erasing result types

Active deduplication and completed-result caching share the same flight actor but solve different problems:

the coordinator owns cache metadata, TTL timers, and LRU order;
the retained flight owns the typed result in Completed(result) or CompletedError(error.Error).

This keeps heterogeneous results out of a dynamic container. The coordinator only needs a pid, approximate size, expiry timer, and access order.

settings.new()
|> settings.cache(
  success: settings.CacheFor(500),
  error: settings.NoCache,
)

The policies are NoCache, CacheFor(milliseconds), and CacheUntilEvicted. Instance-wide item and byte limits bound retained state. The byte size comes from Erlang external-term encoding, so it is an approximation rather than process-heap usage.

Successes and SingleFlight runtime errors have separate retention policies. Nil is cached like any other successful value.

LRU and TTL eviction send Stop to the retained flight. Expiry messages include both the operation identity and pid, preventing an old timer from deleting a replacement flight for the same key.

Backpressure

BEAM can run many lightweight processes, so these settings are application limits rather than the VM's process limit. They make overload visible and predictable before memory, scheduler time, sockets, ports, or the downstream service become the real bottleneck.

A slow key may collect many waiting subjects, while many distinct keys create a flight actor and callback worker each. The runtime therefore has separate controls:

Setting	Bounds
`max_waiters`	Callers attached to one active flight.
`settings.max_flights`	Distinct keys executing at once.
Cache item and byte limits	Completed state retained by the runtime.

When the active-flight limit is reached, a new key receives TooManyFlights, while a duplicate key may still join its existing flight.

The useful number is not “how many processes can BEAM theoretically open?” It is how much concurrent work this application and its dependencies can handle. TooManyWaiters and TooManyFlights provide explicit failure paths instead of letting load grow until another resource fails.

Per-operation handles may change timeout, retry, cache, and waiter policies. Active-flight and cache resource limits belong to the already running instance, so creating another handle cannot resize shared runtime capacity.

The current implementation coordinates one BEAM node. A future distributed version could route a scoped key to one owner node and spread different keys across the cluster. That requires real distributed ownership and failure handling; simply hashing a key or increasing the worker count would not prevent duplicate execution during node failures or inconsistent cluster views.

Summary

Working with several processes and supervisors required a better understanding of how the BEAM actually behaves: who owns state, how messages are ordered, what links and monitors do, and which process a supervisor should restart.

“Let it crash” does not mean ignoring failures. Here it means running user code in an unlinked worker, monitoring it, and keeping the flight actor alive to handle the result, timeout, crash, or retry for its callers. The coordinator and supervisors then handle recovery at the level where state can be rebuilt safely.

Single flight was a useful exercise because the public idea is small, while the implementation touches most of these process boundaries without needing a large application around it.

Gono - an experimental Hono wrapper in Gleam

Andrii Shupta — Fri, 18 Sep 2026 00:00:00 +0000

🔗 Links

Why I built Gono - Experimentation 🟡

I wanted to learn Gleam by building something real.

Not a large product or a new web framework. Just a small library that would force me to go beyond basic language examples.

I chose Hono because I already understood its API. The experiment became Gono: a Gleam wrapper around Hono for JavaScript runtimes.

My goals were simple:

learn Gleam through working code;
understand package and library design;
use the Foreign Function Interface, or FFI;
connect typed Gleam code with an existing JavaScript library.

The wrapper eventually worked. I could define routes in Gleam, run the application on Node or Bun, use middleware, and test requests without starting a real server.

But the most useful lesson was not about routing. It was about the boundary between two languages.

Calling JavaScript from Gleam is easy. Making every value and failure cross that boundary in a predictable form takes much more care.

Gleam application
  → public Gono API
  → JavaScript FFI
  → Hono

Hono values and JavaScript failures
  → FFI conversion
  → Option / Result / Promise / custom types
  → Gleam application

This article shows the parts of Gono that helped me understand that flow. The project is still experimental, but the same lessons apply to many JavaScript wrappers.

Full example

Before looking at the wrapper internals, this is what a small Gono application looks like. It combines the same APIs covered by the project tests: a base path, middleware, request context reads, response context writes, and multiple routes.

Because this example uses the Node runtime, the application must have hono and @hono/node-server installed through its package.json.

src/main.gleam can then define and start the API:


pub fn main() -> Nil {
  let assert Ok(instance) =
    gono.builder()
    |> gono.with_host("0.0.0.0")
    |> gono.with_port(3000)
    |> gono.new

  let api =
    instance
    |> app.use_(fn(c) {
      let _ = c |> context.set_res_header("x-api-version", "v1")

      c
      |> context.next
      |> promise.await(fn(_) { context.continue() })
    })
    |> app.with_base("/api/v1")
    |> app.get("/users/:id", fn(c) {
      let user_id =
        c
        |> context.req
        |> context.req_param("id")
        |> option.unwrap("unknown")

      c
      |> context.json(json.object([
        #("id", json.string(user_id)),
        #("name", json.string("Example user")),
      ]))
      |> context.reply
    })
    |> app.post("/users", fn(c) {
      c
      |> context.set_status(201)
      |> context.json(json.object([
        #("id", json.string("usr_123")),
        #("created", json.bool(True)),
      ]))
      |> context.reply
    })

  let assert Ok(_server) =
    api
    |> node.builder
    |> node.serve

  Nil
}

The middleware runs before both endpoints and writes a response header. GET /api/v1/users/:id reads a path parameter from the request context, while POST /api/v1/users changes the response status and returns JSON. The rest of the article explains the wrapper decisions behind this API.

A binding is not yet a good wrapper

A basic binding answers one question: how can Gleam call this JavaScript function?

A useful wrapper also decides what the JavaScript API should feel like in Gleam. This matters when the original library uses:

mutable instances;
null or undefined;
callbacks with several possible outcomes;
promises that can reject with any JavaScript value;
runtime-specific resources such as Node and Bun servers;
variadic functions and JavaScript arrays.

Hono uses all of these patterns. Gono therefore needed more than direct bindings. It needed its own application type, handler and middleware results, runtime errors, and pipeline-friendly functions.

Keep foreign values opaque

The first decision was how much Gleam should know about a Hono object.

Gono does not try to model all of Hono's internal state in Gleam. It declares the value as an opaque foreign type:

pub type Hono

The type has no constructors that a Gono user can call. A value of type Hono can only come from the wrapper. The same approach is used for Hono's request context and response objects:

pub type GonoContext(body)

pub type GonoRequest

pub type GonoResponse

JavaScript creates and operates on these values. Gleam controls where they can be used. A caller cannot create a fake Hono context or depend on its internal fields.

The JavaScript side can document the real shape with JSDoc:

/**
 * @typedef {import("hono").Hono} Hono
 * @typedef {import("hono").Context} Context
 */

JSDoc gives JavaScript tooling useful information, while the Gleam declaration protects callers on the Gleam side. Neither validates the runtime boundary by itself.

Define small FFI functions

An external function has no Gleam body. @external tells Gleam which JavaScript function to call:

@external(javascript, "./gono/gono_ffi.mjs", "new_hono")
fn new_hono() -> Result(Hono, String)

The type annotation is required, but Gleam cannot verify the JavaScript implementation. It cannot prove that the function exists or returns the declared type.

The JavaScript implementation must return the representation expected by compiled Gleam code:


  try {
    return $gleam.Result$Ok(new Hono());
  } catch (error) {
    const original = JSON.stringify(error);
    return $gleam.Result$Error(`GONO_ERROR_NEW:${original}`);
  }
}

The wrapper keeps the raw string error private and maps it to a Gleam error type:

pub type GonoError {
  GonoErrorMissingModule
  GonoErrorUnsupportedVersion
  GonoErrorNew(original: String)
  GonoErrorUnknown
  GonoErrorRuntime(derived: String)
}

pub fn new(builder: GonoBuilder) -> Result(Gono, GonoError) {
  new_hono()
  |> result.map(fn(hono) {
    Gono(hono:, host: builder.host, port: builder.port)
  })
  |> result.map_error(string_error_to_gono_error)
}

This gives callers a normal Gleam Result instead of exposing a JavaScript exception. The declaration describes the contract; the JavaScript code still has to keep it at runtime.

Keep the public API natural in Gleam

I did not want users to configure Gono through a JavaScript-shaped object. The configuration is normal Gleam code:

pub opaque type GonoBuilder {
  GonoBuilder(host: String, port: Int)
}

pub fn builder() -> GonoBuilder {
  GonoBuilder(host: "0.0.0.0", port: 3000)
}

pub fn with_host(builder builder: GonoBuilder, host host: String) -> GonoBuilder {
  GonoBuilder(..builder, host:)
}

pub fn with_port(builder builder: GonoBuilder, port port: Int) -> GonoBuilder {
  GonoBuilder(..builder, port:)
}

The builder functions return a new Gleam value. They do not mutate a configuration object and they are designed for the pipe operator:

let assert Ok(instance) =
  gono.builder()
  |> gono.with_host("localhost")
  |> gono.with_port(3000)
  |> gono.new

The resulting Gono value contains both the foreign Hono application and the runtime configuration:

pub opaque type Gono {
  Gono(hono: Hono, host: String, port: Int)
}

The instance keeps configuration beside the Hono object without exposing its internal shape. It also separates building configuration from creating the foreign object.

Wrap mutation in a pipeline-friendly API

Hono's registration methods mutate an application and return the same Hono instance:


  return app.get(path, handlerOrMiddleware);
}

Gono keeps this behavior inside JavaScript, but presents a pipeline API in Gleam:

pub fn get(
  instance: gono.Gono,
  path: String,
  handler: gono.GonoContextHandler(body),
) -> gono.Gono {
  instance
  |> gono.get_hono
  |> app_get(path, unwrap_handler(handler))
  |> gono.set_hono(instance, _)
}

Gono returns a reconstructed wrapper after registration, while Hono keeps mutating its application object. This is not real immutability. It is a pipeline-friendly interface around controlled JavaScript mutation.

Gono includes a small reference-identity test to ensure rebuilding the wrapper does not clone the foreign object:

let hono = gono.get_hono(instance)
let updated = gono.set_hono(instance, hono)

gono.hono_same_ref(gono.get_hono(instance), gono.get_hono(updated))
|> should.be_true

The API reads functionally, but registering a route still changes Hono. The wrapper improves composition; it does not pretend that Hono works differently.

The result is readable route composition:

let app =
  instance
  |> app.get("/health", fn(c) {
    c
    |> context.text("ok")
    |> context.reply
  })
  |> app.get("/users/:id", user_handler)

Gleam's pipe operator passes the value on the left as the first argument to the next function. Put the wrapper's main subject first so callers can compose operations naturally.

Make handler results explicit

Hono handlers may return a response immediately or through a promise. Gono makes those two cases visible in the type:

pub type GonoHandlerReply(body) {
  GonoReplySync(response.Response(body))
  GonoReplyAsync(promise.Promise(response.Response(body)))
}

pub type GonoContextHandler(body) =
  fn(GonoContext(body)) -> GonoHandlerReply(body)

The helpers make both branches explicit:

pub fn reply(response: response.Response(body)) -> gono.GonoHandlerReply(body) {
  gono.GonoReplySync(response)
}

pub fn reply_async(
  response: promise.Promise(response.Response(body)),
) -> gono.GonoHandlerReply(body) {
  gono.GonoReplyAsync(response)
}

The adapter then normalizes both forms into the JavaScript contract, which is a promise of a response:

fn unwrap_handler(
  handler: gono.GonoContextHandler(body),
) -> GonoFfiContextHandler(body) {
  fn(context, next) {
    let context = context_bind_next(context, next)

    case handler(context) {
      gono.GonoReplySync(response) -> promise.resolve(response)
      gono.GonoReplyAsync(response) -> response
    }
  }
}

The caller can see that a handler may finish now or later. The adapter converts both cases into the promise-based shape expected by Hono.

Put policy in Gleam

Most JavaScript functions in Gono are deliberately small:


  return app.notFound((context) =>
    handler(context, () => Promise.resolve(undefined)),
  );
}

The wrapper's policy stays in Gleam. For example, a custom not-found handler defaults to 404 only when the response still has status 200:

fn with_default_status(
  response response: response.Response(body),
  status status: Int,
) -> response.Response(body) {
  case response {
    response.Response(status: 200, ..) -> response.Response(..response, status:)
    _ -> response
  }
}

fn with_default_not_found_status(
  handler: gono.GonoContextHandler(body),
) -> gono.GonoContextHandler(body) {
  fn(context) {
    case handler(context) {
      gono.GonoReplySync(response) ->
        response
        |> with_default_status(404)
        |> gono.GonoReplySync

      gono.GonoReplyAsync(response_promise) ->
        response_promise
        |> promise.map(fn(response) { with_default_status(response, 404) })
        |> gono.GonoReplyAsync
    }
  }
}

This became an important rule for Gono:

JavaScript handles mechanics that require Hono or runtime objects.
Gleam owns defaults, variants, error mapping, and composition.

The JavaScript file stays focused on interop. The behavior that Gono owns remains visible and testable in Gleam.

Model middleware flow instead of hiding it

Hono middleware has two useful outcomes:

call next() and let the downstream handler continue;
return a response early and stop the chain.

Gono represents that distinction directly:

pub type GonoMiddlewareReply(body) {
  GonoReplyNext
  GonoReplyAsyncNext(GonoHandlerReply(body))
}

pub type GonoMiddleware(body) =
  fn(GonoContext(body)) -> promise.Promise(GonoMiddlewareReply(body))

The context helpers cover continuing the chain and returning either a synchronous or asynchronous response. Callers do not need to know what undefined means to Hono middleware:

pub fn continue() -> promise.Promise(gono.GonoMiddlewareReply(body)) {
  gono.GonoReplyNext |> promise.resolve
}

pub fn reply_next(
  response: response.Response(body),
) -> promise.Promise(gono.GonoMiddlewareReply(body)) {
  response
  |> reply
  |> gono.GonoReplyAsyncNext
  |> promise.resolve
}

pub fn reply_async_next(
  response: promise.Promise(response.Response(body)),
) -> promise.Promise(gono.GonoMiddlewareReply(body)) {
  response
  |> reply_async
  |> gono.GonoReplyAsyncNext
  |> promise.resolve
}

A middleware that adds a header and continues can be written as:

fn request_id(c) {
  let _ = c |> context.set_res_header("x-request-id", "123")

  c
  |> context.next
  |> promise.await(fn(_) { context.continue() })
}

An early response is a different outcome:

fn forbidden(c) {
  c
  |> context.text("forbidden")
  |> context.reply_next
}

The adapter converts these outcomes to Hono's middleware contract:

fn unwrap_middleware(
  middleware: gono.GonoMiddleware(body),
) -> GonoFfiMiddleware(body) {
  fn(context, next) {
    let context = context_bind_next(context, next)

    middleware(context)
    |> promise.await(fn(next_result) {
      case next_result {
        gono.GonoReplyNext -> promise.resolve(dynamic.nil())
        gono.GonoReplyAsyncNext(handler_result) ->
          case handler_result {
            gono.GonoReplySync(response) ->
              response |> as_dynamic |> promise.resolve
            gono.GonoReplyAsync(response_promise) ->
              response_promise |> promise.map(as_dynamic)
          }
      }
    })
  }
}

This is also why context.next is a wrapper function instead of a plain field access. The actual Hono next callback is supplied by JavaScript and bound to the context before the Gleam handler runs:

const NEXT_SYMBOL = Symbol.for("gono.next");

  context[NEXT_SYMBOL] = next;
  return context;
}

  const next = context[NEXT_SYMBOL];
  if (typeof next !== "function") {
    return Promise.resolve(context);
  }

  return Promise.resolve(next()).then(() => context);
}

The symbol keeps this bridge private and reduces the chance of a property collision. Gleam users only see context.next, not the mutable value attached to the JavaScript context.

The main lesson: contain JavaScript failures

This was the most important lesson from the project.

A JavaScript function can throw immediately. A promise can reject later. A server can start successfully and emit an error afterward. If one of these failures crosses the FFI boundary unchanged, it becomes much harder to reason about from Gleam.

The Gleam JavaScript promise type deliberately does not include a generic error type because JavaScript can reject with any value. If an operation needs a typed success-or-failure contract, put the Result inside the promise:

promise.Promise(Result(value, error))

For a new external call, the boundary can look like this:

@external(javascript, "./provider_ffi.mjs", "load_text")
fn load_text(url: String) -> promise.Promise(Result(String, String))



  try {
    const response = await fetch(url);

    if (!response.ok) {
      return $gleam.Result$Error(`HTTP_${response.status}`);
    }

    return $gleam.Result$Ok(await response.text());
  } catch (error) {
    return $gleam.Result$Error(String(error));
  }
}

Now the promise resolves in both cases. Success becomes Ok, and a recoverable failure becomes Error. Gleam receives the value described by the external function instead of an unexpected rejected promise.

Gono uses this boundary selectively:

new_hono catches construction failures and returns a Gleam Result.
Node and Bun server creation catch runtime failures and map them to runtime errors.
URL query parsing catches invalid URL failures and returns Error(Nil).
The mock request helper is intentionally a small async bridge used by tests.
Hono route and middleware promises can still reject; Hono catches handler and middleware errors and sends them to onError.

This does not mean adding try/catch around everything. Catch a failure when the wrapper can turn it into a useful value. If Hono already owns that failure path, preserve Hono's behavior instead of swallowing it.

For a promise that already contains a Result, promise.try_await continues the callback only for the Ok branch. The surrounding function still returns a promise of a result:

fn read_example() -> promise.Promise(Result(String, String)) {
  use text <- promise.try_await(load_text("https://example.com"))

  promise.resolve(Ok(text))
}

If the error needs to be handled at that point, use promise.await and match on the result explicitly.

For callback-based APIs, adapt the callback once with promise.new, then keep the rest of the flow in Gleam.

Convert values once, at the edge

Gleam lists and JavaScript arrays are different runtime representations. Gono converts them in the FFI rather than making every public function expose JavaScript-specific details:

function middlewares_to_array(middlewares) {
  let cursor = middlewares;
  const converted = [];

  while (!(cursor instanceof $gleam.Empty)) {
    converted.push(cursor.head);
    cursor = cursor.tail;
  }

  return converted;
}

That helper lets JavaScript call Hono's variadic API:


  return app.get(path, ...middlewares_to_array(middlewares), handler);
}

The reverse conversion is needed for values returned from JavaScript:


  const headerEntries = list_to_array(headers);
  const request = new Request(`http://localhost${path}`, {
    method,
    headers: new Headers(headerEntries),
  });
  const response = await app.fetch(request);
  const body = await response.text();
  const responseHeaders = Array.from(response.headers.entries());

  return [response.status, body, $gleam.toList(responseHeaders)];
}

The public Gleam test API can therefore use normal Gleam collections:

runtime_mock.request(app, http.Get, "/hello", [])

The same principle applies to optional values. Hono may return undefined for a missing parameter or header, so Gono converts it to option.Option:


  const value = req.param(name);
  return value == null ? Option$None() : Option$Some(String(value));
}

Then a Gleam caller can decide how to handle absence instead of receiving undefined:

let id =
  c
  |> context.req
  |> context.req_param("id")
  |> option.unwrap("missing")

This code depends on Gleam's generated JavaScript representation, such as $gleam.Empty and $gleam.toList. I keep that dependency inside the FFI module so the rest of Gono does not need to know about it. It is also an obvious place to re-test after a Gleam upgrade.

Convert values once, close to the FFI, and keep the rest of the wrapper idiomatic Gleam.

Separate Node and Bun

The Hono application is JavaScript-runtime agnostic, but starting a server is not. Gono keeps Node and Bun adapters in separate modules:


let assert Ok(server) =
  instance
  |> node.builder
  |> node.on_process_event("SIGTERM", fn(_server, _error) { Nil })
  |> node.serve

The Node FFI checks the environment before calling the Node adapter:


  if (!is_node_env()) {
    return Result$Error("NODE_ERROR_INVALID_ENV");
  }

  try {
    const server = serve({
      port: gono.port,
      hostname: gono.host,
      fetch: gono.hono.fetch,
    });

    // Register process and server events here.
    return Result$Ok(server);
  } catch (error) {
    return Result$Error(`NODE_ERROR_SERVER:${String(error)}`);
  }
}

The Gleam module maps those strings into a closed error type:

pub type NodeError {
  NodeErrorInvalidEnv
  NodeErrorUnsupportedVersion
  NodeErrorServer(original: String)
  NodeErrorUnknown
}

The try/catch only handles failures during setup. A Node server can emit an error after it has started, so Gono also registers an error event listener. These are separate failure paths and both need handling.

This keeps Node-specific behavior out of the core wrapper. Gono uses the same structure for Bun.

Use tests as documentation

The Gono tests show how I expect the wrapper to be used. They also verify the part the Gleam compiler cannot see: whether JavaScript really returns the promised representation.

Test the instance boundary

The instance tests verify defaults, builder overrides, and the identity of the foreign Hono object:

pub fn gono_defaults_test() {
  let instance =
    gono.builder()
    |> gono.new
    |> should.be_ok

  instance |> gono.get_host |> should.equal("0.0.0.0")
  instance |> gono.get_port |> should.equal(3000)
}

Test routes through the mock runtime

The mock adapter executes the actual Hono app in memory. That makes route tests fast and avoids binding a network port:

pub fn hello_route_test() -> promise.Promise(Nil) {
  let assert Ok(instance) = gono.builder() |> gono.new

  let app =
    instance
    |> app.get("/hello", fn(c) {
      c |> context.text("hello") |> context.reply
    })

  runtime_mock.request(app, http.Get, "/hello", [])
  |> promise.map(fn(result) {
    result.0 |> should.equal(200)
    result.1 |> should.equal("hello")
    Nil
  })
}

Test middleware outcomes separately

Gono's context tests cover both sides of the middleware contract:

a middleware can mutate a header and continue to the handler;
reply_next can stop the chain synchronously;
reply_async_next can stop it with a promise response.

The difficult part of a wrapper is often not the direct method call. It is preserving callback order and return-value semantics across two languages.

Keep long-running server tests out of `gleeunit`

Gleeunit exits the process when test execution finishes. A test that starts a real Node or Bun server should use a dedicated integration or end-to-end runner instead of relying on the unit-test process to stay alive.

What I would repeat

If I write another JavaScript wrapper in Gleam, I will follow the same rules:

Identify the smallest foreign values that need to cross the boundary.
Represent them as opaque Gleam types.
Give every external function an explicit type annotation.
Convert JavaScript undefined and nullable values to Option or Result.
Convert lists and records at the FFI edge.
Use custom types for meaningful sync, async, continue, and early-reply outcomes.
Put try/catch around JavaScript operations that can fail synchronously.
Handle later callback, event, and promise failures through their own channels.
Return Promise(Result(...)) when an async operation has a typed error contract.
Keep runtime-specific adapters separate from the core wrapper.
Test the contract the compiler cannot see: foreign identity, callback order, promise behavior, value conversion, and error paths.

What I got from the experiment

Gono is a small project. It was never meant to replace Hono or become a large framework.

It did what I needed: the wrapper worked, I could run it on Node and Bun, and the tests described a usable Gleam API around Hono.

More importantly, it changed how I think about interop. The happy-path call is usually the easy part. The real work is deciding what happens to mutation, missing values, callbacks, exceptions, rejected promises, and runtime errors when they move between languages.

An FFI type is a promise to the compiler, not proof about JavaScript at runtime. The boundary becomes reliable only when the JavaScript implementation, Gleam types, and tests all describe the same behavior.

That lesson was more valuable than the wrapper itself.

Connect Polkadot to a Next.js website with @polkadot/extension-dapp

Andrii Shupta — Sat, 17 Dec 2022 09:34:11 +0000

🔗 Links

📰 Published on

🤓 Intro

As a developer, it's essential to understand the differences between various blockchain platforms to choose the right one for your needs. One key difference(as for me) is the availability of technical resources and tutorials for developers. Ethereum has many articles and tutorials demonstrating how to connect a wallet to a website, whereas there is less information available on Polkadot. This may make it easier for developers who are new to Ethereum to get started and learn how to build applications on the platform.

It's important for developers also to be familiar with Polkadot and how to build on its platform, as it has unique features and potential applications.

Developer Experience outside just documentation is quite important nowadays for the web3 community.

In this article, I will show an example of how to connect a SubWallet(that's what I have used) to a Next.js website.

Technology

On Ethereum, we have web3.js and ethers.js for connecting to a website and many different libraries built on top of it. For example, many projects I have seen use wagmi with React.js. It is just a blessing, such as it includes a full list of functionality that you need to have to interact with blockchain: "Connect Wallet" display ENS and balances information, sign messages, interact with contracts, and much more — all with caching, request deduplication, and persistence.

Polkadot has production-ready libraries and tools to work with blockchain, and one of them is @polkadot/extension-dapp. That's what we would use to "Connect Wallet".

🧑‍💻 Coding

We will use the default Next.js app, so nothing is new here. Check out Getting Started to remind yourself of Next.js.

The most crucial point with @polkadot/extension-dapp is that it needs a browser to run, so with Next.js, we need to render the "Connect" button only during Client-Side rendering. For that, we would use dynamic import.

🔗 source code

On the Home page, we load our Connect component dynamically. Connect components are where all magic happens.

🔗 source code

Let's start with imports:

InjectedAccountWithMeta is a type of account that we would get. I imported it for TypeScript.

Our main focus here is web3Enable and web3Accounts .

I have used promise chaining down below, but if you prefer try-catch + async / await - go for it!

`web3Enable`

The initial function is to call even to check if our browser has any wallets to work with. In case we don't have anything to work with, the extension shows it in the console, and we also should throw an error to show the user that he should use the browser with a valid Wallet.

`web3Accounts`

Same with web3Accounts - it would load accounts connected or prompt you to connect to the website if you opened it for the first time - a very familiar experience for web3 users.

You could try out the flow on polkadot-extension-dapp-example | Deployed on Vercel, and it looks like this:

Disclaimer: I have tried only when I have 1 wallet, but for a simple example, it should be enough.

🧑‍🏫 Next steps and more examples

With a connected wallet and available account, you can do everything you want: check out how to create and sign a transaction, show <Identicon/> and more:

https://polkadot.js.org/docs

A more mature example using @polkadot/api , @polkadot/ui-keyring and more is PolkaVerse. It is a decentralized social network built on Subsocial - "The Blockchain for Social Finance".

Also, I have another project where I tried to use Subsocial API - it is raw-raw-raw cause it was fine for me to connect to Subsocial API and Polkadot to experience how things work. Feel free to check it out: https://github.com/andriishupta/subtips-app

Thanks for reading! 🙇

Simplify usage of Lens API with @use-lens and graphql-codegen

Andrii Shupta — Tue, 04 Oct 2022 11:05:21 +0000

🔗 Links

📰 Published on

🤓 Intro

Recently, I have used Lens API to build some playground apps and noticed a repetitive task: I created Lens API Queries and Mutations for every project and used GraphQL Code Generator to use React hooks with Apollo Client.

After 2nd time doing the same job, I decided to create a library for easier use of Lens API that would save me some time to do actual work.

I have never created open-source packages and thought it would be a great experience to do it, even if only I would use it 😅.

npm @use-lens so far contains 2 packages - CLI and react-apollo. Later in this article, I will explain how to use them and when, and the same information could be found in the repo's README.md.
I will explain how I see the best use of @use-lens/* later in the article.

Also, I liked Lens Protocol so much that I have created Github Organization Use Lens, where I plan to develop and publish some tools, examples and apps working on top of Lens.

Technology

Lens Protocol is a composable and decentralized social graph, ready for you to build on so you can focus on creating a great experience, not scaling your users.

Own your content. Own your social graph. Own your data.

If you have read so far - you know what Lens API is and how to use it. If you are here to check out @use-lens or just to check how to generate GraphQL code - educate yourself of Lens Protocol and API here:

🌿 https://docs.lens.xyz.

GraphQL Code Generator - is a tool to build read-to-use code from your GraphQL schema and operations with a simple CLI with a lot of plugins for different frameworks: React, Next.js, Svelte, Vue with Apollo, URLQ and others - you name it.

🧑‍💻 How to

Generate with @use-lens/cli

npm install --save-dev @use-lens/cli
use-lens generate %PACKAGE%

with npx

npx @use-lens/cli generate %PACKAGE%

This would copy essential files of Lens API to your repo and would run graphql-codegen to generate the code. By default, it would go to src/lens-api/index.ts.
From here, you could adjust tsconfig.json to use it with @use-lens shortening, so it would feel like a package usage. More on how to do it here.

With `@use-lens/*`

The simple npm install --save @use-lens/%PACKAGE% and use it as a regular package.

import {
  GlobalProtocolStatsDocument,
  GlobalProtocolStats as GlobalProtocolStatsType,
  useGlobalProtocolStatsQuery,
  useGlobalProtocolStatsLazyQuery,
} from '@use-lens/react-apollo'

Manual GraphQL Code Generator

The default approach is simple and could be followed by official docs here

On high-level:

install @graphql-codegen/cli
pick a plugin for your stack: for example, react-apollo and install it
get your GraphQL Schema and Documents
create basic codegen.yml for graphql-codegen
run graphql-codegen

In your codegen.yml, you should specify schema, documents, where to save, and with what:

schema: schema.graphql # full schema; could be HTTP link
documents: documents.graphql # queries and mutations that you want to have
generates:
  ./src/my-api/index.ts: # where to save
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo # stack that you are going to use

⚠️ CAUTION

🌿 https://docs.lens.xyz/docs/introduction:

This API is beta and not production complete yet, which means that we could change schemas and endpoints at any time without warning or notice to you. When this API is production ready, we will remove this beta warning and will endeavor to ensure that there are no changes going forward unless a major change to the protocol itself is required.

Lens API is not production complete, and so is @use-lens/*. Please, keep this in mind when going to production.

Recommended use

If you want to play with Lens API - don't hesitate and install some of the @use-lens/* packages - it will give you all you need to start.

If you want to have more control - use @use-lens/cli to generate code locally. This would copy essential files that a package contains and would run graphql-codegen.

You would be able to do more with codegen.yml.

👨‍🏫 React with Apollo Client

For @use-lens/react-apollo, I have prepared an example of how to use it.

Check out the source code here

🤝 Lens API Documents

The complete set of Lens API Documents has been taken from api-examples, a repo of Lens Protocol that shows how to use Lens API.
The same (or similar) queries are given as examples in Lens API docs.

📚 Summary

If you would like to use Lens API to see what it is - simplify your developer experience by using @use-lens or GraphQL Code Generator.

Thanks for reading! 🙇

Create Lens Subgraph on The Graph Protocol

Andrii Shupta — Fri, 26 Aug 2022 10:21:20 +0000

🔗 Links

📰 Published on

✨

Initially, I got familiar with TheGraph by contributing to DeveloperDAO to a project that did the same - indexing Lens Protocol.
P.S. This tutorial is NOT copy-paste of existing code, and I created a repository from scratch to understand the basics of TheGraph and how to start. I needed to develop my subgraph to test how events would be indexed.

🤓 Decentralized querying

The Graph is an indexing protocol for querying networks like Ethereum and IPFS. Anyone can build and publish open APIs, called subgraphs, making data easily accessible.

Many different tools and APIs help us query blockchain data using centralized API like we used to with web2. My favourites are alchemy and infura.

But, if we want to go decentralized, we must use decentralized tools.

All data is stored and processed on open networks with verifiable integrity. TheGraph makes querying this data fast, reliable, and secure.

Lens

Lens Protocol is a composable and decentralized social graph, ready for you to build on so you can focus on creating a great experience, not scaling your users.

Own your content.
Own your social graph.
Own your data.

With Lens API, we could do everything we want with protocol, but it still includes the web2 principle and has a centralized database for different things built on top of Smart Contract data.

If we want to get actual blockchain data, we need to use a protocol like TheGraph.

Disclaimer: assumption about the centralized part of Lens API is based on the features that Smart Contract has not, for example: "likes" functionality.
I like Lens API very much and would count on it 99.9% of the time as a personal preference, balancing centralized vs. decentralized tooling.

👀 How to create a subgraph

In this tutorial, I will give an example of creating a subgraph using Hosted Service - it will be closed in months. Still, there won't be a difference in coding approaches, just in how it is internally deployed. With the Hosted Service, it was easier to use for testing purposes.

graph init

install graph-cli
run graph init --product hosted-service
follow CLI steps where you need to add protocol, name, and contract address

You will get a generated project. The main entry point is subgraph.yaml.
This is the finished version of my subgraph.

🔗 source code

You can read more on what is subgraph manifest

source block

Indicates from what address to index. Many contracts use Proxy Upgrade Pattern, which helps to fix crucial bugs or update implementation. That is why I have added LensHub ABI(Application Binary Interface) as source ABI and then changed the address to proxy
startBlock - I chose some random block for testing purposes, so it won't start indexing from the start - it takes more time. Usually, this value is omitted or equals the Contract creation's block.

To get ABI, you can:

Copy from Etherscan/Polygonscan whole Contract ABI
Go to remix.ethereum.org, copy the github project, and compile the contract

I went with a 50/50 approach, such as Lens has Events.sol library that is not compiled as part of the main contract.

`graph codegen`

After proper setup, we can run code generation - we will get all types of code to work with.

✨ The Graph has excellent documentation, so follow it and find all answers there. ✨

Mindset shift

As a developer who worked with databases, I started to think linearly: entity created -> entity updated. But events could be indexed from startBlock and in non-linear order in time, so even if we index the event like handleProfileImageURISet, we need to check if the entity existed previously(more in the code example).

To find more tips, TheGraph documentation has a section "defining entities" - it entirely describes what you should think about when creating your schema.

Before defining entities, it is important to take a step back and think about how your data is structured and linked.

Code

As we know - schema and how our data would be created is essential. Let's look at how I have added entity definition:

🔗 source code

Profile is the @entity, including default fields that I took from ProfileCreated event and the posts field, which is an entity relationship

In this case, it is a "One-To-Many" relationship with the usage of the Reverse Lookup approach that TheGraph recommends us using.

For one-to-many relationships, the relationship should always be stored on the 'one' side, and the 'many' side should always be derived. ... will result in dramatically better performance for both indexing and querying the subgraph...

Post is also an @entity. Both have an ID, which should be unique for the subgraph.

In lens-hub.ts are located functions that correspond to events we want to index.

`handle*Created`

As we see, even for a new Post, we check if Profile already exists or not. I discovered the error I got during subgraph deployment and indexing that was saying something like "profile cannot be null" when I just wanted to load Profile to Post.

TheGraph also supports the "merge" approach - this means that if we create a new instance of Profile and it already exists - it is okay cause the subgraph would try to merge fields. I wanted to be the more precise cause in the examples, and I saw that in every place where we wish to create something - we first check if it could be already created.

Example: I have created a Post, and the subgraph knows that Post should have a Profile. Profile event was way before Post, so we don't have a Profile, and we need to create it; even if you could think - "how a Post could be created without a Profile" - it couldn't, but the event about the Post we could get first to index.

🔗 source code

✅ Testing

To check out how it works, you could visit my subgraph: andriishupta/hello-world. It has a pre-defined "Test" query that will give you info for both Profiles and Posts. You could modify it to get more or less information in the query window.

🙇

Thanks for reading!

Generate Dummy Data in Strapi

Andrii Shupta — Tue, 16 Aug 2022 11:27:00 +0000

🔗 Links

github: andriishupta/strapi-generate-seed-data
Strapi's video with a general idea of how to "Generate dummy data"

📰 Also published on

🤓 Motivation

Strapi is powerful open-source headless CMS that helps projects control code customization with extensibility and, at the same time, don't worry about implementing a full-blown Content Management System on their own.

So, after you have set up your Strapi, you want to build Front-End on top of it. You hire front-end developers who are stuck: "Ye, I can query for data via REST and GraphQL, but what data should I see? Could I have an example?"

😬

To avoid this, we would generate example data upfront.

🌱 How to seed data?

"Generate dummy data"

There is the video in Strapi's Video-library that gave me a direction on how to do it.

The idea is simple:

use bootstrap function
use Entity Service API for interactions
generate dummy data with @faker-js/faker

Tip

Your case 💯 would be more complicated, so don't forget that you could take almost everything from Strapi's source code.

The flow:

find a place on Strapi Admin you want to copy
check URL and Network(in developer's inspection) to understand what is called
find code(start with controller) that corresponds to that calls
enjoy

🧑‍💻 Code

We have a simple Todo application(duh) with a Todo collection and a Todo List as a page(single type) that we want to send to the front-end. Also, our Todos has media functionality, so we upload some.

In the bootstrap function, we check for the development environment and decide if we should run seeding or not. Seeding would automatically run on the very first application run(valid when a developer clones an existing repository) and could be re-run with yarn seed to force seed, which clears old and creates new data - FORCE_APP_BOOTSTRAP_ONLY.

🔗source code

Collection Type

To create a todo using Entity Service API, we need to call the create method with data that matches our entity. In the current example and during seeding, I have used "bulk promises" to run requests in parallel cause they are not dependent on each other.

🔗 source code

And using faker, we fill a todo like this:

Single Type

Fulfilling the "Todo List page" is the same as Collection, but keep in mind that it could be only one entry all the time. Also, it contains a Todo relation, so we get five todos to fill it.

🔗 source code

Media Upload

To attach media on a todo, we first need to upload that media and then link its id to the entity. Code has been copied from Strapi's source code, modified, and I just created a helper function.

🔗 source code

Example in Todo:

✅ Results

After opening the Admin panel, you will see generated data.

✨

Initially, I implemented this for Developer DAO's website developerdao.com. Original code is located here(archived and moved to monorepo).

Thanks for reading!

Setup Supabase with Nest.js

Andrii Shupta — Tue, 16 Aug 2022 05:35:50 +0000

❗️⚠️ Disclaimer

This article is created for Supabase v1 and seems not to work with v2 due to the depreciation of some auth methods. I will create a new article for v2 and leave it here. If you have already found a solution — let me know in the comments! Thanks!

🤓 My expectations from You

You know what the Supabase is
You know the Nest.js framework
You will google what is beyond this tutorial if needed

🤔 My use case for using Supabase in Nest.js

I needed a polling mechanism that runs every 1 second and does some action.
As Auth and DB, I have chosen to use Supabase cause I have seen some tutorials and wanted to try it out.

At first, I wanted to use Next.js and Functions to do those operations by Cron Jobs, but it happens to be that the minimal time frame for Cron Job by Github(as the most accessible Cron provider) is only every 5 minutes.

So I switched to the idea of a server(full) app with Nest.js. (want to deploy on Heroku)

🧑‍💻 How to use Supabase and Nest.js

There is one single example of how to use Supabase as Auth library for your Nest.js application, but:

it didn't seem straightforward (actual implementation) to me, and I didn't want to use an external package
it doesn't work as I wanted - it didn't have Supabase Client exposed from within the lib

it is still a good entry if you have never used Passport and need an example - it helped me to understand what to do in my code, so thanks **hiro1107* :)

📑 examples: https://supabase.com/docs/guides/examples

🧑‍💻 Github: https://github.com/hiro1107/nestjs-supabase-auth

So I have decided to implement my way for Auth and Client.

Could we use Supabase on the Node.js back-end?

In general, like Firebase, Supabase is a client-side tool that works from the client-side by providing the "anon" user with Row Level Security Policies, but it doesn't force us to use Supabase only on the client-side.

With some rules, we can freely leverage the power of Supabase in our Node.js Server.

🍴 Supabase basic setup

There are a few key points that I want to mention before the code.

RLS Policies

Enable it when you create tables

I recommend creating two by default:

"anon" is rejected by default for ALL actions
ALL actions are only could be done by auth.uid(), if your app is "user-oriented"

`user_id`

To make your application work with previous policies, don't forget to create the user_id column on each table that you use: it should be NOT null auto-generated auth.uid() field, so in this way, Supabase will always append the correct user to a row.

You can bypass RLS with Service Keys if needed, but be careful.

🐱 Nest.js application

Installs

To make this work, we need to add a few libs in addition to Supabase:

npm i passport passport-jwt @nestjs/passport @supabase/supabase-js

passport - handles everything related to Auth, does it magic that we don't need to care about

passport-jwt - has a ready-to-use Strategy for JWT Auth

@nestjs/passport - Nest.js's module for Passport

How JWT Auth works with Passport

How JWT Auth works go beyond this article, but there are plenty of explanations for using Passport and passport-jwt in Nest.js. You can start by checking Nest.js's Authentication.

What we need to know for our case: Supabase is JWT-based authorization, which handles everything on its side. On our side, we need to have the correct SUPABASE_JWT_SECRET, which is used to decode JWTs. (located in Settings -> API)

Supabase folder

🔗 Link to folder

This is the main code you could copy to your code base, and it will just work. The module is a regular Nest.js module. Other files deserve a deeper look.

Strategy

Passport has a rich ecosystem of strategies that implement various authentication mechanisms. While simple in concept, the set of Passport strategies you can choose from is large and presents a lot of variety

Such as Supabase is JWT, we will use a ready-to-use passport-jwt strategy that does all decoding and other things for us.

In this code, we extend PassportStrategy with JWT Strategy and pass config in the super call.

strange "extend" PassportStrategy(Strategy) is TypeScript Mixins

🔗 source-code

Guard

With this guard, I have protected the whole application by providing APP_GUARD in app.module.ts - a global way of guarding. You could use UseGuard for routes that need to be protected.

Here we extend AuthGuard with the jwt strategy(this is how passport-jwt named Strategy under the hood). Easy.

🔗 source-code

Service: `Scope.REQUEST`

This service will createClient for every request and setAuth, so we will have the correct user during all following service calls. Code implemented in "Singleton" manner so we will get the same instance in different places during the same request.

🔗 source-code

Why?

Here comes an interesting part that happens with different libraries that hold client-side states:

If we use client-side libs that hold state per user, on server OR SSR apps like Next.js, we need to be careful with those, such as it could be that when we create an instance of a library, it could become available for everyone who calls server/SSR apps.

That is why it is essential to use @Injectable({ scope: Scope.REQUEST }) so our Supabase createClient will be created per request, and we will set auth correctly.

Another example: Next.js & SSR with react-query

Disclaimer: I haven't tested it for multiple users yet, but I am pretty sure about it.
I haven't found other ways to pass Auth with one Client in docs by appending access_token - only setAuth to Client directly.

Possible solution: Supabase could tweak auth flow, where with a unique setup, we can pass users in each request. With the Passport, we have the user in req.user and can still access the Authorization header for access_token.

📭 Testing with Postman

After everything is finished - let's try to call our server.

As expected, we get a 401 code - this is passport.js does it check for JWT in our SupabaseGuard

Let's now get a valid access_token and repeat the call:

💪 💪 💪

access token available after you log in with a user. In my case, I have just sent "Magic Link" and got acces_token from the URL

📋 Summary - TL;DR;

install required dependencies
copy supabase folder to your project
add 3 SUPABASE_* variables to .env
import supabase.module: in app.module / @global() auth.module / etc.
provide global APP_GUARD or use it where you need it with UseGuard
use supabase.ts in other services by this.supabase.getClient() for Supabase calls

🔗 Links

Github: https://github.com/andriishupta/nestjs-supabase-setup
Nest.js's Authentication, including JWT with Passport.js
How to use Guards in Nest.js
Supabase's Auth example app with Nest.js
Supabase's docs
Link to Medium's copy of the article

Thanks for reading!

Cross-Origin iframe communication with Window.postMessage

Andrii Shupta — Tue, 16 Aug 2022 05:19:00 +0000

🤔 Why do we need cross-origin iframe communication?

Imagine that you need to integrate with the "3rd party service" that would be used as part of your application.

Both of your companies are just start-ups, and we don't have a complete variety of tools that will make our lives easier, so we choose iframe as the first option. We must integrate what we have now for the beta version. After that, we will refactor the code and will use edge technologies, as our manager promised(😉)

Their app(as an example) could show private information, possibly, some real-time bank details / shipping / trading details, and only available after user authorization.

🤓 What could be a better solution?

The best version of integration(IMHO) would be to get a react library with components, hooks, utils, etc., that will do everything for us. For example, check out React Stripe.js Components. Second best - take an Open API(example Stripe API) and implement our own components.

🤨 What are we going to build?

💭 Idea summary

As the Parent app, we want to login within the iframe with some token, so the iframe could show relative information. Every N mins(5 secs in this case), our token would expire, and the iframe needs to request another. As a bonus, we can change a theme from dark to light, which could happen from both sides.

Mostly I would list code that is only related to the iframe and Web API part and won't focus on things like an app creation or an explanation of "how to deploy to Vercel".

The Parent and the Child apps would be our actual implementation of what we need. For the front-end, we are going to use Next.js and Chakra-UI for components. We would deploy apps on Vercel and Netlify(to be truly cross-origin).

Also, I would use Nrwl Nx's workspaces to have monorepo, keeping run/build processes seamless.

👨‍💻 Code(skip to this if you don't want to read the Intro)

🤖 "The Communicator."

🔗 https://iframe-communicator.vercel.app

🔗 Github: https://github.com/andriishupta/iframe-communicator

It is a "special" app you could use for real-world testing to see how messaging works in your app.

🧑 Parent code

🔗 link to the deployed app

🔗 source code is available for copying here

As for the Parent app, we will surely have iframe rendered on our side. Let's start from it:

iframeRef is our React.js reference to the DOM element, so we can later use it
onLoad - this would send my initial token

Next: how we send the message is Window.postMessage

The window.postMessage() method safely enables cross-origin communication between Window objects; e.g., between a page and a pop-up that it spawned, or between a page and an iframe embedded within it.

const postMessage = (message: Message) => {
    iframeRef.current.contentWindow.postMessage(message, CHILD_APP_URL); // OR use '*' to handle all origins
};

postMessage takes a message: Message as the argument - it is our own message kind that we selected and agreed with the Child app to pass through:

The data is serialized using the structured clone algorithm. This means you can pass a broad variety of data objects safely to the destination window without having to serialize them yourself.

To send actual message we are using iframeRef.current.contentWindow as our targetWindow(from documentation) and the function's second parameter is targetOrigin:

Specifies what the origin of targetWindow must be for the event to be dispatched, either as the literal string "*"

I know my targetOrigin, so I am passing it and suggesting you not neglect security risks.

Last but not least, we want to listen to messages from the Child!

Security and filtering: we accept only our messages that we are sure in

// skip other messages for security reasons and avoid extensions alerts in console
if (event.origin !== CHILD_APP_URL) {
  return;
}

Now, let's get the data from the MessageEvent and do some checks and act by business logic:

if (message?.type === 'token-expired-from-child') {
  ...
} else if (message?.type === 'theme-from-child') {
  ...
} else {
  //  in case of some random message
}

*for more options this code could be improved with switch/case(who likes), ternary operator, or object literals.

Finish up by adding a listener and return a callback for removal, so when a component goes down, you navigate to another page, where you don't need to listen for an iframe.

window.addEventListener('message', handler);
return () => window.removeEventListener('message', handler);

👶 Child code

🔗 link to the deployed app

🔗 source code is available for copying here

The approach is the same for the Child app, with a twist of where to call postMessage - window.parent.

And listening to the messages differs in type.

🔗 Links

🎨 Parent app: https://cross-origin-iframe-communication-with-nextjs-parent-app.vercel.app

👨‍💻 Github: https://github.com/andriishupta/cross-origin-iframe-communication-with-nextjs

🤖 "The Communicator": https://iframe-communicator.vercel.app

👨‍💻 Github for "The Communicator": https://github.com/andriishupta/cross-origin-iframe-communication-with-nextjs

📝 Summary

Cross-Origin iframe communication could come in quite handy in specific situations, and we totally could take advantage of two-way messaging to make that even more dynamic. Check for yourself by clicking the examples.

Thanks for reading!

DEV Community: Andrii Shupta

Encois: Building Organizational Intelligence on Google Cloud

🔗 Links

The idea

Why this is more than a RAG chatbot

A release-safety example

Starting with system design

Product concepts and immutable execution

Events, Sources and changing context

Temporal as the execution source of truth

One Coordinator per organization

Generic Blueprint execution

Bounded agents and deterministic boundaries

Contracts are part of the architecture

Clear ownership across Google Cloud

Permissions must survive the Workflow

Turning the dashboard into an operational view

Current limits and next steps

Summary

MiyKo: A Durable AI Workflow for Shared Shopping

🔗 Links

The idea

Why a shared order changes the product

Keeping the architecture small

The complete MiyKo flow

1. One workflow keeps the process together

2. Different people see the same order

3. Silpo stays a separate trusted system

4. Previous purchases become useful memory

5. The plan exists before the real basket

6. The workflow pauses for approval

7. The agent prepares a real basket

8. Checkout still belongs to Silpo

Memory, not chat history

Reworking the app UI

Summary

I Built a Fasting App I'd Actually Use. Apple Rejected It.

🔗 Links

The app I wanted to use

Building it with AI, without giving up the decisions

Where faster coding made the app heavier

The screen had the final say

What I take from this

Directing a 3D Web Experience with AI

🔗 Links

The idea

I started from the result, not the code

Technically correct can still look wrong

Why Three.js was difficult to review

What Astro, GSAP, and Three.js each did

Performance became a visual problem

Mobile needed a different answer

What I had to give the agent

What I learned

Single Flight in Gleam: Managing Processes with OTP

🔗 Links

The idea

A complete example

The BEAM mental model

Why operations live in an application record

The key defines equivalent work

The process topology

The coordinator

The flight supervisor

One flight is a state machine

Monitoring, linking, and “let it crash”

Retries belong to the flight

Supervision and recovery boundaries

call and send

Caching without erasing result types

Backpressure

Summary

Gono - an experimental Hono wrapper in Gleam

🔗 Links

Why I built Gono - Experimentation 🟡

Full example

A binding is not yet a good wrapper

Keep foreign values opaque

Define small FFI functions

Keep the public API natural in Gleam

`call` and `send`

Keep long-running server tests out of `gleeunit`

`web3Enable`

`web3Accounts`

With `@use-lens/*`

`graph codegen`

`handle*Created`