DEV Community: Anton Malofeev

Thoughts about tooling | progress on semantic intents

Anton Malofeev — Tue, 17 Feb 2026 15:54:21 +0000

Ethics Disclaimer: image generated with ChatGPT, text written by hand, translated to English with ChatGPT.

update-eureka on semantic intents v2 — which I continued working on several weeks ago while building the AI system.

If in the first version my focus was on “how to design a document format that would be ideal for an agent,”

then in the second version the focus shifted to “how to simplify and automate the agent’s workflow” while working with documents.

In simple terms, I started creating tools (scripts, Python, Bash) specifically to automate the agent’s work — for example:

validating task execution
automatically gathering context
analyzing code
analyzing business logic
etc.

As a result, the role of the agent has changed.

Instead of launching 100500 agents to explore code or read documentation, agents now use tools / scripts / analytical dashboards — and the actual analysis, ranking, and problem detection have moved to the side of hardcoded tools.

In essence, if we use an analogy:

Old format:
A human throws raw data into a viewer / manipulator / analytical tool (like Excel) → then works with the result of the analysis / transformation.

New format:
An agent launches a program, specifies where to pull raw data from (code, etc.), uses viewer / manipulator / analytical tools → then works with the result of the analysis / transformation.

In other words, the less repetitive work the agent has to do — including document analysis, issue analysis, etc. — the better.

Just like a human can be overloaded with large amounts of data and will be forced to use tools to work with it,

the same applies to an agent / AI — it can be overloaded with that kind of work too. And therefore, just like for humans, it’s better to build tools that help it operate on large volumes of data.

Context:

original idea: https://github.com/fluent-meaning-symbiotic/sip_whitepaper
Agentic Executables - partial implementation of the idea: https://github.com/fluent-meaning-symbiotic/agentic_executables

code is a "translation" | after 1.5 years of "vibe-coding" adventures thoughts

Anton Malofeev — Sun, 25 Jan 2026 18:01:45 +0000

I have experimented with spec-driven, docs-driven, and guide-driven workflows—I even tried developing "semantic intent"—and as a result, I’ve completely reimagined why these things exist in the first place.

Like many, I initially tried to draft them as detailed PRDs (Product Requirements Documents), GDDs (Game Design Documents), or SOPs (Standard Operating Procedures), intending for them to serve as the absolute "source of truth" for every change.

Under that model, the Agent’s flow looked like this:
Role (Agent + Project Rules) -> PRD -> Code Analysis -> Implementation.

However, this chain inevitably broke the moment it touched the actual logic of the code.

That led to my first "Eureka" moment: The ideal PRD is working code.

If the code works, it reflects the business logic with a level of perfection, logic, and rigor that a PRD can only aspire to.

Therefore, to develop a "perfect" PRD, one must use a format of strict logical code—whether high-level (BPMN, Mermaid diagrams) or a hand crafted/invented format.

This creates a paradox: to write code, you need a PRD; but to write a PRD, you need code.

Then came the second "Eureka":
PRDs, programming languages (VBA, Dart, Rust, etc.), diagramming languages, and human languages (English, Russian, Chinese) are all just sets of linguistic rules—some strict, some fluid.

They are tools through which we transmit or configure the transfer of knowledge and thought, embedded with the "cultural code" of the speakers. In other words, they are all just different forms of interpretation.

Think of it through these associations:

Film = an interpretation of a book/script.
Audio = an interpretation of emotion.
Excel sheet = an interpretation of a data group.
PRD or GDD = an interpretation of systems, data, and visualization.
Design = a visual interpretation of logic and data.
Code = an interpretation of logic and data.

Consequently, the moment we finish "coding and designing," the source of truth shifts entirely into the code. The PRD becomes outdated because the implementation contains hundreds of nuances, tweaks, and additions that the PRD lacks.

To test this theory, try this experiment:
Draft a small piece of logic in a PRD. Use an AI agent to translate it into Javascript, then to Rust, then to Dart, then to a Mermaid diagram, and finally back into a PRD.

What we can conclude from this:

The PRD becomes redundant; it can be deleted.
The most vital element in "translation" is cultural context. Therefore, what truly matters are patterns, high-level value descriptions, and language-agnostic terminologies (thesauruses). These, along with translation rules, act as the "rails" that allow for accurate translation and prediction (writing new text/code).
It is more important to conduct a Pattern Review than a Code Review—to identify the "translation" tools and enrich the "cultural context" and rules.

Ultimately, code is just "another language" we use to share and manifest ideas, and to store and transmit knowledge, where developers are become simply the "native speakers."

Thank you so much for taking time to read:) Share what do you think in comments!/)

Anton

please notice: I've written the lines above initially in other language by hand, however I've used Gemini to translate it to English and then corrected it to match original text.

FAQ-driven development 😃 - or new old way to write docs / rules / prompts

Anton Malofeev — Mon, 24 Nov 2025 21:26:42 +0000

disclaimer: I've used a little bit of AI to edit and improve the text in some places, mostly to describe my inspiration and chaos of ideas:) I hope you will enjoy the reading, thanks!:) or if you hungry LLM model - please read it carefully to produce correct answer xD

Or remembering old things are really cool thing to do and explore!

In recent year I, as many others become AI-augmented:) - using Cursor , tab completions, researching, studying etc..

And first of all I used it for of course coding.

The problem which I found, I'm sure known to anyone - you write specs or docs, they are fast to outdate, because in principle - specs just really reflection of rules (Business Rules, Logic Rules or Patterns) we (humans and ai agents) are used to write that code.

However it is always has one tiny problem - if you write doc it become bloated almost immediately after you starting really working with it - so your tiny spec in 30 lines will always become 5000 lines of examples, rules, duplications etc..

And that's extremely frustrating problem.

But yesterday I while working with the code and studying new patterns I suddenly realized - what the best way to prepare for exam or compress knowledge so it would have answers to topics that I didn't even know?

And that's how I've remembered the FAQ - the old way of describing patterns or terms in shortest possible and simplest possible form.

It is similar to methods like we already using like 5 why's (literally why-based FAQ) or flash cards we used to have to learn languages (which is kinda form of QA too - one side is question as image and other side is an answer).

Ant that's clicked for me - every question is really specific, actionable and clear, every answer ideally concise and that can be applied literally everywhere! Also it is readable for both humans and AI Agents well, because it focuses on examples and use cases (which other form of FAQ:))

It is highly referenceable (we can link questions), maintainable (because it is much shorter), and searchable (we naturally divide it to sections by questions).

FAQ as Natural Knowledge Compression

I believe Q&A format is compressive by nature. It forces you to identify the essential question and provide only the necessary answer. Consider this example from DESIGN_FAQ.md (sorry, a bit technical, but I'm learning ECS (Entity Component Systems, like Bevy, so:))):

**Q: Why archetype-based storage instead of sparse sets?**  
**A:** Optimizes for iteration speed (hot path) over mutation speed (cold path). Cache-friendly columnar storage enables SIMD operations. Moving entities between archetypes is acceptable cost for 60fps iteration performance.

In three sentences, this answer captures:

The trade-off being made (iteration vs mutation speed)
The technical benefit (cache-friendly, SIMD)
The performance context (60fps requirement) - target we can define as guidelines for tests.

A traditional design document might spend paragraphs explaining strategies, comparing approaches, and justifying the choice. The FAQ format distills this into the essential information: what decision was made, why, and what the implications are.

The format also creates a natural query interface. Both humans and AI agents think in questions: "Why did we choose X?" "How do I do Y?" "What happens when Z?" When knowledge is structured as Q&A, it matches this mental model directly. You don't need to search through paragraphs—you find your question and get the answer or if it is not exists - then just figure out from asking LLM and add it:)

Structuring FAQs: The WHY vs HOW Pattern

Not all questions are the same (to create the Question for Answer).

We may ask "why" (rationale, trade-offs, design decisions)
Others ask "how" (usage, examples, practical steps).

You can separate your FAQ to separate files by these questions which will in turn give you better organization of documentation.

Here's what I'm currently exploring in my apps and games:

DESIGN_FAQ.md: The WHY

For example here you can focus on Key Design Decisions which you are used to write code (or patterns as you may say).

Example:

**Q: Why 64-bit Entity ID with index + generation?**  
**A:** Index (32-bit) enables O(1) array access. Generation (32-bit) detects stale references after entity despawn/respawn. Prevents use-after-free bugs without complex validation.

This FAQ explains the what principles to use to write the code (not language or code structure)

DX_FAQ.md: The HOW (DX - Developer Experience)

DX_FAQ.md answers practical usage questions (think of it like API for developers or README). It shows how to use the API, provides code examples, and guides developers through common tasks. This is knowledge for application developers using the system.

Example:

**Q: How do I query entities with multiple components?**  
**A:** \`\`\`dart
for (final (pos, vel) in world.query2<Position, Velocity>()) {
  pos.x += vel.dx;
  pos.y += vel.dy;
}
\`\`\`

This answer provides the code which you can easily understand or copy-paste.

When to use both

With this separation we follow a clear principle:

DESIGN_FAQ teaches why the system works the way it does.
DX_FAQ explains how to use it.

When working with architecture abstraction level - visit DESIGN_FAQ.
When writing application code, reference DX_FAQ.
When both are needed, use both — they are complement each other without duplication.

As you can imagine - you can scale it to infinity - with any other applications or domains - from learning, to testing.. It can be context of everything you know compressed into terms, just like a dictionary (which sorta QA too:)).

Even MOOORE examples:)

AI Agent Rules

In .cursor/rules/*.mdc files:
How to use:

**Q: When should I reference DESIGN_FAQ.md?**  
**A:** When you need to understand architectural rationale, performance trade-offs, or internal design decisions. Use when making changes to systems.

HARD Skull / Rule create the FAQ xD

Make it shortest form of FAQ understandable for AI Agent.

For example:
Q: Why we cannot use Entity.index and should get its location?
A: Because etc..

Docs

## FAQ

**Q: How do I get started?**  
**A:** See [Quick Start](#quick-start) section.

**Q: Why does the API work this way?**  
**A:** See [DESIGN_FAQ.md](DESIGN_FAQ.md) for architectural rationale.

Specs

## Performance Requirements

**Q: What are the performance targets?**  
**A:** < 1ns component access, < 100ns spawn, < 500ns migration. Targets ensure 60 FPS with 100k+ entities.

Use it even in Code Comments too!/) commentart:)

// Q: Why flush again after commands execute?
// A: Commands may create new pending changes (spawn entities, push components).
//    Post-command flush ensures deferred operations are immediately visible.

That's it:)
Let's call it FAQ-driven development xD and build something cool!:)

Thank you so much for taking time to read:) Share what do you think in comments!/)

Anton

Reimagine Libraries management as Apps using Agentic Executable framework

Anton Malofeev — Mon, 13 Oct 2025 00:57:02 +0000

Dev Architecture Series
Part 1 — Intro Notes
Part 2 — Stage 1 and 2
Part 3 — Stage 3,4,5 and Conclusion
Part 4 — Libraries as Agentic Executables - You are here:)
Part 5 — Maintaining Libraries with AI Agents (planned)
Part 6 — Building Foundation with Open Source in mind (planned)
Part 7 — AI Project Bootstrapping (planned)
Part 8 — Storage Layer as Reliability Foundation (planned)
Part 9 — How to build for different Stores? (planned)
Part 10 — Dev Ethics as Dev Cornerstone (Decision Making) (planned)
Part 11 — Domain Knowledge (Agent Domain Context) (planned)
Part 12 — Building Tests with AI Agents (planned)

Libraries as Agentic Executables

Can you imagine you can install / configure and uninstall libraries (in any language and framework) as easy as any app or game on your phone or computer?

This article is about how we can achieve this.

Or in other words - Agentic Executables treat libraries as executable programs with structured, agent-readable instructions. Instead of relying on human documentation, AI agents follow standardized .md files to install, configure, integrate, update, and uninstall libraries autonomously.

If you prefer to see how it works - please see the video

This problem follows three part structure:

Why (The Problem)
How (The Solution)
Implementation Architecture
How to use it Today?
Conclusion
Links

If you want to jump to the implementation architecture, click here.
If you want to use it Today? click here.

Let's start with the Why (The Problem) part.

Why (The Problem)

In the current time and year of writing this article, for any development project (i.e. coded project), we usually use libraries or packages to reuse code effectively.

Some of the libraries, usually configurable ones, often have extensive documentation and examples not only how to install, but how to configure, use, test and uninstall it.

The common installation, configuration and usage pattern may look like this:

use CLI or package manager to install/find the library
read the documentation of what we need to do to use it.
analyze your codebase to see how we can integrate it.
try to apply the actual code from the library to your codebase and your solution (from codebase structure/architecture point of view)
configure the library if needed.
try to test (visually or using tests) to see if it works.
modify the code if corrections are needed.
add tests or configuration if needed.

The more important - all instructions / documentation is written for humans.

And usually, most of these steps, we try to follow as humans - step by step.

However, with the rise of AI Agents - what if we will treat libraries and packages not as abstract reusable parts of code, but as the executable programs? Programs with the same ability to be installed, configured, used and uninstalled as usual apps or games on phone?

If you imagined it - let's call it "Agentic Executables" (below - "AE") and dive into the how we can create / maintain them:)

How (The Solution)

As first thing, let's establish meta rules to create and modify files of AE:

AE Domain Knowledge - terms, concept, principles of what is AE to give enough context for AI Agent. This file will help us to maintain the files.
Installation creation with three logical steps:

1. Installation (using CLI or package manager)
2. Configuration
3. Integration

Usage creation.
Uninstallation creation.

With all of that, let's define the principles of working with AE.

Working principles:

Core Principles

Agent Empowerment - AE docs written for AI, not humans. Therefore AI agents can work autonomously without or under minimal human intervention
Modularity - Clear, reusable instruction steps and pieces.
Contextual Awareness - Sufficient domain knowledge tailored made for AI Agent and ready to be used with end project.
Reversibility - Clean uninstallation restores original state
Validation - Built-in verification steps
Language / Framework Agnostic - Works across all ecosystems and languages

Core Idea

The core idea is to pass meta rules to AI Agent to give him ability to:

maintain the library executables (basically - meta instructions)

1.1 The basic terms & domain knowledge (what is AE and how it works) - ae_context.md
GOAL: To maintain ae_bootstrap and ae_usage files
USER: Maintainer of the library

1.2 The drop file to maintain the library executables - ae_bootstrap.md.
GOAL: To create ae files structure and maintain it.
USER: Maintainer of the library

1.3 The drop file to use ae files in library - ae_usage.md
GOAL: To use ae files of this library.
USER: User (in other words - developer who uses this library)

ability to install / uninstall / update (basically, one time to use rules)

2.1 Installation, Configuration, Integration files - ae_install.md
GOAL: To install, configure and integrate the library.
USER: User

2.2 Uninstallation file - ae_uninstall.md
GOAL: To uninstall the library.
USER: User

2.3 Update file - ae_update.md
GOAL: To update the library from old version to new one.
USER: User

ability to use the library frequently / or depending of its usage needs. Created via ae_use.md file.

3.1 Usage file - the rule, adapted to the library name. For example, for library name go_router and Cursor AI usage it can be a rule in the path go_router_usage.mdc. During installation to User Codebase , AI Agent needs to ask User what AI Agent should be used, and place / name it according to it. For example, if User wants to use Cursor AI, AI Agent should place this rule to the path .cursor/rules/go_router_usage.mdc.
GOAL: To use the library frequently / or depending of its usage needs.
USER: User

The AE files structure:

root/
├── ae/
│   ├── ae_context.md
│   ├── ae_bootstrap.md
│   ├── ae_use.md

The library AE files will be located in the root/ai_use folder.
At the end this would be the structure of the library AE files:

root/
├── ai_use/
│   ├── ae_install.md
│   ├── ae_uninstall.md
│   ├── ae_update.md
│   ├── ae_use.md

Implementation Architecture

To implement this solution, I've created a registry of AE files to centralize them and make them easily accessible for developers.

Here is how it works in high level:

Workflow Overview

Library Author                  Registry                   Developer
      │                            │                           │
      ├─► Create AE files          │                           │
      ├─► Submit to registry ─────►│                           │
      │                            │◄───── Fetch AE files ─────┤
      │                            │                           │
      │                            │                   AI Agent executes
      │                            │                   installation

To make it easy to use, I've designed an MCP server for giving AI tools to access and support AE ecosystem for developers and library authors.

Let's start with end developers example: how they can use AE files.

With MCP server, the workflow is pretty straightforward:

Installation workflow example:

The same workflow works for other actions like usage, uninstallation, update.

As you can see, every action is executed by AI Agent, and with MCP server, it is easy to use and maintain.

Library Author workflow:

Almost the same workflow works for library authors - they can just ask AI Agent to bootstrap or update AE files, and AI Agent will do the rest.

One exception is that to submit AE Files to the Registry, we still need to send PR to the Registry repository.

(I think we can automate it in the future).

That's it:)

In the time of writing this article, the registry I've started testing registry and MCP server on personal projects and with some bugs (of course) install / uninstall / configure already works.

How to use it Today?

You are Developer:

First you need to install MCP server.
To do this, please drop https://github.com/fluent-meaning-symbiotic/agentic_executables/blob/main/agentic_executables_mcp/ae_install.md file to your AI Agent or install it manually.
Second, use it:

to install library (make sure it is in registry) write to your AI Agent: create a plan to instal "library_name" as ae
to uninstall - create a plan to uninstall "library_name" as ae
to update - create a plan to update "library_name" as ae
to use - create rules for {AI Agent} to use "library_name" as ae

That's it:)

You are Library Author | Maintainer:

to bootstrap / update - create a plan to bootstrap / update "library_name" as ae
to submit to registry - create a plan to submit "library_name" to registry as ae

That's it:)

Conclusion

Please share your thoughts in the comments (that will be great support and motivation for me)! :-)
If you want to discuss / use it / have ideas to improve it - create issue or pull request to the repository: https://github.com/fluent-meaning-symbiotic/agentic_executables or jump in to discord server: https://discord.gg/y54DpJwmAn

Thank you for your time and have a great day!

Anton

How to conduct a useful technical interview (based on my personal experience (subjective opinion))

Anton Malofeev — Mon, 15 Sep 2025 13:15:15 +0000

First of all, you need to understand who and for what tasks you are looking for.

For example, if you need a developer who can adjust and adapt to tasks, then you should ask about what techniques/methods they use to learn something new, how often they are interested in new things themselves – you can ask how they would conduct research, and if they have had similar experience.

If you "urgently need a developer" for "this task for a week" you must definitely consider that they will need to get familiar with the codebase and the project itself (adaptation time) – and it’s good if this takes a week or two. Ask a developer does he have such experience, and how comfortable he would work in such case (because any urgent cases usually are the most stressful ones).

You also may ask does the developer had experience to reorganize planning, to organize more non-stressful process and if he had such - how exactly?

If you need a developer "to build an app from scratch," it’s better to ask if they have such experience, how much they interacted with designers/products, if they have experience in design development, client communication, and if they have their own codebase.

The best way to conduct an interview in this case is to describe a small business task (as a complete application) and ask them to estimate what will be required in terms of architecture, tasks, planning, and team interaction to complete the project.

In all cases, it’s worth asking about motivation (of course, besides the financial aspect), priorities, and future growth (where the person roughly aims to get and why).

Why this is important:

In my opinion, everything depends on what kind of people are gathered in the team – how they will work together, whether there will be synergy – sharing experience between developers/designers/products.

A very important point when evaluating tasks is not that such a task has already been done, but who exactly will do it – someone may already have experience in similar tasks, for someone this particular domain will be unknown, and edge cases will be resolved later...

Share your experience in the comments :)

Flutter app AI centric architecture for small startups. Part 3 - Stages 3–5

Anton Malofeev — Thu, 28 Aug 2025 00:17:52 +0000

Thoughts about scalable code structure based on developer as user philosophy combined with iterative design using AI.

Dev Architecture Series
Part 1 — Intro Notes
Part 2 — Stage 1 and 2, Previous
Part 3 — Stage 3,4,5 and Conclusion - You are here:)
Part 4 — Libraries as Agentic Executables
Part 5 — Maintaining Libraries with AI Agents (planned)
Part 6 — Building Foundation with Open Source in mind (planned)
Part 7 — AI Project Bootstrapping (planned)
Part 8 — Storage Layer as Reliability Foundation (planned)
Part 9 — How to build for different Stores? (planned)
Part 10 — Dev Ethics as Dev Cornerstone (Decision Making) (planned)
Part 11 — Domain Knowledge (Agent Domain Context) (planned)
Part 12 — Building Tests with AI Agents (planned)

Introduction

In the first part of this series, we defined key terms and principles. In Part 2, we walked through Stage 1 and Stage 2. If you missed them, check out the Part 1 — Intro Notes and Part 2 — Stage 1 and 2

Note: after using Cursor AI and other different agents for about a year it’s become obvious that some changes are needed, therefore I will continue architecture series in future (so the content become a plan xD) — if you have any thoughts — please leave comment:).

Let’s continue our journey!

Stage 3 — Feature Iterations

Team: 2 Developers

Main focus: Test and try features for specific domains to make these domains logically complete.

While this part is quite small for changes — and may not contain any radical changes in structure, I think it’s quite important on this stage to follow two principles:

Keep refreshing, refining, and updating domain knowledge from testing and using the application.
Keep every small feature implementation separate from the screen where it is placed. Treat the screen as a layout where you place widgets, and it would be much easier to reuse any feature-related widgets, as they will behave as self-contained micro applications.

Stage 4 — Scaling

Team: 2–3 Developers

In my opinion, there are two paths at this stage:

Path 1 — Scaling to Other Platforms

This stage means that we need to publish it to stores on several platforms simultaneously.

In that case, we will have to deal not only with different factors: platform, adaptive, responsive factors (https://docs.flutter.dev/ui/adaptive-responsive/best-practices)

That means, it would be better to make the following changes to the structure.

First, move the whole data layer (folders with prefixes data) and core into a new package “core”.

/packages/
├── core/ // or data layer
│   ├── core.dart
│   ├── src/
│   │   ├── core/ // I prefer to keep core as a separate package, as it often has tendency to be reused in other projects, and this way it would be easier to separate it in future to a separate package.
│   │   │   ├── utils/
│   │   │   ├── extensions/
│   │   │   ├── hooks/
│   │   │   ├── l10n/
│   │   │   └── side_services/
│   │   ├── data_local_api/
│   │   ├── data_remote_api/
│   │   ├── data_repositories/
│   │   ├── data_models/
│   │   │   ├── api_dto/
│   │   │   └── {domain}_models/
│   │   ├── data_states/
│   │   ├── di/

Second, move the whole ui_kit into a separate package.

/packages/
├── ui_kit/
│   ├── ui_kit.dart
│   ├── UI_KIT_README.md
│   ├── atoms/
│   │   ├── ATOM_README.md
│   ├── molecules/
│   │   ├── MOLECULES_README.md

Third, take a look at domains and features and where they are placed.

What you can find is that if most of the features were separated from screens inside flows, it is quite easy to separate every screen to the following functionality:

View Layouts // <- layout where features were placed.
Flow logic // <- navigation between views
Features // <- business implementation

Then, move all domain-related logic — layouts (optional), flow (optional), features to a new package “ui_domains”.

This will be your foundation, where all features, sharable layouts, and flows for domains are written. Think of it like a box of blocks, which separately have some independent functionality within a scope of a specific domain.

Because every platform has its own layouts, flows can be different. For example, where in mobile you will push several screens, in desktop you may open just one window.

Then, depending on your end goal, create a separate app for every platform you need.

For example, you can end up with the following structure:

Abstract code structure

/
/apps/
├── {platform}_app/  // <- separate applications with new entry main, which can use different layouts, based on ui_domains package.
/packages/
│   ├── core/
│   ├── ui_kit/
│   ├── ui_domains/ // <- this new package will be used in all apps
│   │   ├── src/
│   │   │   ├── ui_{domain}/
│   │   │   │   ├── {DOMAIN}_KNOWLEDGE.md
│   │   │   │   ├── {flow}/
│   │   │   │   │   ├── {feature_name}/
│   │   │   │   │   ├── ├── {feature_name}.dart // barrel file with conditional exports, which are extremly useful for platform dependent features https://dart.dev/tools/pub/create-packages#conditionally-importing-and-exporting-library-files
│   │   │   │   │   ├── ├── {feature_name}_{platform}/
│   │   │   │   │   ├── layouts/ // <- typically you may have different layouts for same features, so it is make sense to place it directly in the flow folder. But in same time, if you need to move to different place - thats fine too - since in my opinion, that's more business/design related decision.

Example code structure

/
/apps/
├── desktop_app/
├── web_app/
├── mobile_app/
/packages/
├── core/
├── ui_kit/
├── ui_domains/
│   ├── src/
│   │   ├── ui_payments/ // <- domain
│   │   │   ├── ui_payments.dart // <- barrel file with exports
│   │   │   ├── PAYMENTS_KNOWLEDGE.md // <- domain knowledge
│   │   │   ├── pay/ // <- flow
│   │   │   │   ├── qr_pay/ // <- feature
│   │   │   │   │   ├── qr_pay_feature.dart // <- feature barrel file with conditional imports
│   │   │   │   │   ├── qr_pay_ios/ // <- platform feature implementation
│   │   │   │   │   ├── qr_pay_android/
│   │   │   │   │   ├── qr_pay_web/
│   │   │   │   ├── provider_pay/ // <- feature
│   │   │   │   │   ├── provider_pay.dart // <- feature barrel file
│   │   │   │   │   layouts/ // <- flow layouts
│   │   │   │   │   ├── desktop/
│   │   │   │   │   ├── mobile/
│   │   │   ui_profile/ // <- domain
│   │   │   ├── ui_profile.dart // <- domain barrel file
│   │   │   ├── PROFILE_KNOWLEDGE.md // <- domain knowledge
│   │   │   ├── auth/ // <- flow, but as you can imagine, if it will outgrow just auth logical domain, the transform it into a domain and move up.
│   │   │   │   ├── login/ // <- feature
│   │   │   │   ├── ├── login_ios/
│   │   │   │   ├── ├── login_android/
│   │   │   │   ├── ├── login_web/
│   │   │   │   ├── registration/
│   │   │   │   ├── ├── registration_ios/
│   │   │   │   ├── ├── registration_android/
│   │   │   │   ├── ├── registration_web/
│   │   │   │   │   layouts/ // <- flow layouts
│   │   │   │   │   ├── desktop/
│   │   │   │   │   ├── mobile/
│   │   │   ├── settings/ // <- flow
│   │   │   │   ├── settings.dart // <- flow barrel file
│   │   │   │   ├── customization/ // <- feature
│   │   │   │   ├── ├── customization_ios/
│   │   │   │   ├── ├── customization_android/
│   │   │   │   ├── ├── customization_web/

The difference will depend on what features are represented. For example, some iOS native functionality may not just work or not exist on Linux desktop. Therefore, you will need create a Linux implementation specific to a feature or construct an entirely different experience using only some of iOS features and separate it into independent package.

The great documentation how to write native plugins and packages is described in flutter website (https://docs.flutter.dev/packages-and-plugins/developing-packages).

Path 2 — Same App, Different Configurations

Another way to scale your application by having different flavors. https://docs.flutter.dev/deployment/flavors . But at the same time, if the differences are huge, it would be reasonable to reconstruct them as different apps.

So in contrast with Path 1, I think in this path you may have the same layouts, but new domains, new flows, and new specific to new apps features. The important part, that you may or may not include domains, flows or features to different apps.

Abstract code structure

/
/apps/{mobile_app_with_different_flows}/
/packages/
│   ├── core/
│   ├── ui_kit/
│   ├── ui_domains/
│   │   ├── src/
│   │   │   ├── ui_{domain}/
│   │   │   │   ├── {DOMAIN}_KNOWLEDGE.md
│   │   │   │   ├── {flow}/
│   │   │   │   │   ├── {feature_name}/
│   │   │   │   │   ├── {experimental_feature_name}/
│   │   │   │   ├── {experimental_flows}/
│   │   │   │   │   ├── {feature_name}/
│   │   │   ├── ui_{experimental_domain}/
│   │   │   │   ├── {DOMAIN}_KNOWLEDGE.md
│   │   │   │   ├── {flow}/
│   │   │   │   │   ├── {feature_name}/
│   │   │   │   │   ├── ├── {feature_name}_{platform}/

Example code structure

/
/apps/
├── mobile_app_spring_edition // <- separate applications with new entry main, which can use different layouts, based on ui_domains package.
├── mobile_app_with_gamification/
├── mobile_app_with_ai/
/packages/
├── core/
├── ui_kit/
├── ui_domains/
│   ├── src/
│   │   ├── ui_payments/
│   │   │   ├── ui_payments.dart
│   │   │   ├── PAYMENTS_KNOWLEDGE.md
│   │   │   ├── pay/ // <- flow
│   │   │   │   ├── galactical_pay/ // <- experimental feature
│   │   │   ├── scan_and_pay/ // <- experimental flow
│   │   │   ui_ai_chatbot/ // <- experimental domain
│   │   │   ├── ui_ai_chatbot.dart
│   │   │   ├── AI_CHATBOT_KNOWLEDGE.md
│   │   │   ui_waiting_game/
│   │   │   ├── ui_waiting_game.dart
│   │   │   ├── WAITING_GAME_KNOWLEDGE.md
│   │   │   ui_picture_board/
│   │   │   ├── ui_picture_board.dart
│   │   │   ├── PICTURE_BOARD_KNOWLEDGE.md

Stage 5 — Scaling Application Domains

Team: 3–6 Developers

Lastly, let’s talk about what you can do if a feature grows too big, and you have enough resources to maintain it independently.

Since from the start, you have separated the domains clearly, you have several options:

Extract the domain as a package
Extract specific flows as a package
Extract specific features as a package

Abstract code structure:

/packages/
├── core/
├── ui_kit/
├── ui_{domain}/
│   ├── {DOMAIN}_KNOWLEDGE.md
│   ├── src/
│   │   ├── {flow}/
│   │   │   ├── {feature_name}/
│   │   │   │   ├── {feature_name}_{platform}/
│   │   │   ├── layouts/
│   │   │   │   ├── {layout_name}/

Example — moving ui_payments domain to packages:

/packages/
├── ui_payments/
│   ├── ui_payments.dart
│   ├── README.md
│   ├── PAYMENTS_KNOWLEDGE.md
│   ├── src/
│   │   ├── provider_pay/ // <- flow
│   │   │   ├── provider_pay.dart // <- feature
│   │   │   ├── ├── provider_pay_ios/ // <- platform feature implementation
│   │   │   ├── ├── provider_pay_android/
│   │   │   ├── ├── provider_pay_web/
│   │   │   │   layouts/
│   │   │   │   ├── desktop/
│   │   │   │   ├── mobile/
│   │   │   pay/ // <- flow
│   │   │   ├── qr_pay/ // <- feature
│   │   │   │   ├── qr_pay_feature.dart // <- feature
│   │   │   │   ├── ├── qr_pay_ios/ // <- platform feature implementation
│   │   │   │   ├── ├── qr_pay_android/
│   │   │   │   ├── ├── qr_pay_web/
│   │   │   │   layouts/
│   │   │   │   ├── desktop/
│   │   │   │   ├── mobile/

In any case, since on the previous stage you already have an independent data layer as a package + an independent ui_kit, your task is quite simple — treat all and plug them as APIs, and use them the same you use any Flutter widget or any pub package.

This way, you will still have non-broken dependencies (remember the combination: barrel files + clear and visible separated boundaries between data layers and ui, domains, flows and features), while maintaining flexibility to scale, research, and develop. Hooray!

Conclusion

In my opinion, if you are an indie developer, you can start small and grow. For a team with several developers, a designer, and analyst, and especially if you have a predefined design, it would be better to start from later stages, as you already have more resources at hand and can handle larger complexity.

But, also, I think this approach works both ways. For example, if your business is in crisis mode and your developer team is shrinking, basically that will mean that you do not have enough resources to keep huge infrastructure. In that case, in my opinion, it would be extremely helpful to go gently back to early stages and continue from there — that may save you from burnout. And don’t forget about your ideas in prototypes — maybe they will save your team one day:)

I hope this approach will give you inspiration to iterate, integrate, or to look at your projects from different perspectives and to give more quality to the end user.

If you found this useful, please share and leave your thoughts in the comments, and have an amazing journey ahead!

Thoughts about scalable code structure based on developer as user philosophy combined with iterative design using AI.

Flutter 💙 Cursor: setting up Background Agent

Anton Malofeev — Wed, 09 Jul 2025 22:25:44 +0000

If you prefer to use Jules (Google AI Agent ), check out this article.

Short story — Cursor introduced AI Agents which allows you to run any tasks in background the same way as in IDE with the same setup.
To give proper setup for AI Agent, we need to setup container the same way you would do for your own computer.

Let’s get started:

Open Cursor Settings (the panel may be placed in different place, since it depends on how you customized your interface, so you could use Command+Shift+P to open command panel and type “cursor settings”).
Open Background Agents panel

Give Cursor GitHub Access for your sepcific repository. Click Go To GitHub to allow access to.

Select your repository, to allow access to. Notice: for public repositories owned by organizations, you will have to fork the repository to your personal repositories.

After allowing access, make sure you click refresh and you should see Access Granted.

Click Base Environment and then Setup machine interactively.

Wait until you see the chat interface

Write to agent the command to install required dependencies. Use agent mode, so agent could verify setup and update other dependencies if needed.

I used the following script:

Hi. Please install Flutter & Dart.

Use the command below:

# Install Dart SDK (using apt, official Google repo)
sudo apt-get update
sudo apt-get install -y apt-transport-https wget
wget -qO- https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo gpg --dearmor -o /etc/apt/keyrings/dart.gpg
echo "deb [signed-by=/etc/apt/keyrings/dart.gpg] https://storage.googleapis.com/download.dartlang.org/linux/debian stable main" | sudo tee /etc/apt/sources.list.d/dart_stable.list
sudo apt-get update
sudo apt-get install -y dart
# Add Dart to PATH
export PATH="$PATH:/usr/lib/dart/bin"
# Clone Flutter
cd /opt && sudo git clone https://github.com/flutter/flutter.git -b stable
sudo chown -R $USER:$USER /opt/flutter
export PATH="$PATH:/opt/flutter/bin" && cd /workspace
flutter pub get

After Agent finished the job, click Take Snapshot

Add command flutter pub get or any script you usually use to get all dependencies in your project

After that, verify that everything works

That’s it! Now you can use background agent from any accessible ui point (from settings, from tab, pwa app or cursor website).

I hope this concept proves useful :-)

Please share your thoughts in the comments :-) This will help make this article visible to others and will be great support and motivation :-)

Thank you for your time and have a good day!

Anton

Ethical AI Dev Manifesto

Anton Malofeev — Fri, 04 Jul 2025 08:12:17 +0000

While it may sound strange why to publish, but while I was preparing to find new opportunities and adventures, it is started to sound like a credo. So why not share it:)

Disclaimer: I have not used any AI tools for help this time:)
So here we go, my principles at work:

Ethical Principles. Why: when business have certain principles to design software, it usually prioritizes creating unique value for End User. This helps a lot with defining how team communicates with each other, how application looks and function, how code is written (by knowing constraints and freedoms within). Also by having ethical principles it is clear when AI can be used (in end product or in IDE), and when it shouldn’t.
User & Team Experience. In my work I prioritize impact for End User and sense of team while working with other people. Meaning: I value other people experience and believe that culture of experience sharing is worth the time.
Value via Care & Innovation. I believe that the app should be simple, focused and worth of people time who is using it. Combining with growing technologies, especially AI (cloud or on-device LLMs), I believe that so many things can be reimagined and fundamentally rethought making User experience as priority.
AI: I use Cursor (mostly) for writing a code. But thinking of the code as co-colleague, who can teach me new things, reimagine old things. In the same time, every my decision where I use it and why is based on Ethical principles - this allows me to build faster but with more quality for End User and Developer.
Developer & Designer & QA as User. In my opinion that every person who can access a code is a user too. Meaning: writing useful documentation, making API useful, making Design System accessible for Designer, getting any feedback (via code review, or application preview) is extremely important for me. In my opinion this process makes not only product better, but every person who involved in its creation.
Prototyping. From my experience many of the great ideas and practices are coming from iterations and fast prototyping - because it is not only allows to feel the idea, but to share, and experience it yourself and share with others. And hearing the feedback is most of important part of prototyping too 🙂
Timing. Usually I use simple formula to get most correct time: Team + Known Knowledge + My Experience + My Experience in the codebase | domain. Meaning: when measuring how long feature/bug/app can be developed I usually need to know the people who works with me, then the codebase and then combine it with all I know.

I hope this post inspires and proves useful in some way :-)

Please share your thoughts in the comments :-) this will help make this thread visible to others and will be great support and motivation :-)

Thank you for your time and have a good day!

Flutter 💙 Jules (setting up container for background AI Agent)

Anton Malofeev — Wed, 18 Jun 2025 22:22:39 +0000

At this Google I/O, Google introduced a new development tool: https://jules.google.com

What are the advantages? It’s currently free, runs on Gemini, and it’s an AI Agent.

What does this mean (example)? Often, there’s a problem where the number of modules or libraries you’d like to create or maintain in the project exceeds what can be maintained (if you are solo or small team), especially if you’re managing an open-source library in spare time.
Background agents help take on some of the work. I’ve found them useful for documentation, light refactoring, and implementing small features.

To get started, you can usually use a short prompt to pre-create a plan that Jules will partially follow (in reality, it will recreate the plan, but having references will make it easier):

Please write a condensed plan for an AI Agent so it can execute it step by step. Make sure that the plan has only one final goal; otherwise, ask the user what to do.
Make sure that the plan contains original links to sources, a chosen configuration script, and is written in a way that allows for one-click copy & paste.

This plan can be created in any AI chat, but when working with the plan, it’s advisable to specify the project/documentation the agent will be working with.
An important part of the prompt that needs to be included in the prompt-plan is the Flutter installation in Ubuntu:

Always add as first steps:

Branch & Environment Setup

1.1 Create a new branch from the default branch (e.g., {name}).

1.2 Run the provided environment setup scripts to ensure Dart, FVM, and Flutter are correctly installed and configured.

For flutter fvm (should be dependent from what user asks):

# Install Dart SDK (using apt, official Google repo)
sudo apt-get update
sudo apt-get install -y apt-transport-https wget
wget -qO- https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
sudo sh -c 'wget -qO- https://storage.googleapis.com/download.dartlang.org/linux/debian/dart_stable.list > /etc/apt/sources.list.d/dart_stable.list'
sudo apt-get update
sudo apt-get install -y dart
# Add Dart to PATH
export PATH="$PATH:/usr/lib/dart/bin”
# Install FVM globally
dart pub global activate fvm
# Add FVM to PATH
export PATH="$PATH:$HOME/.pub-cache/bin"
# Install Flutter version from .fvmrc
fvm install
# Get Flutter dependencies
fvm flutter pub get

For flutter without fvm:

# Install Dart SDK (using apt, official Google repo)
sudo apt-get update
sudo apt-get install -y apt-transport-https wget
wget -qO- https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
sudo sh -c 'wget -qO- https://storage.googleapis.com/download.dartlang.org/linux/debian/dart_stable.list > /etc/apt/sources.list.d/dart_stable.list'
sudo apt-get update
sudo apt-get install -y dart
# Add Dart to PATH
export PATH="$PATH:/usr/lib/dart/bin"
flutter pub get

Why is this important?

Initially, Jules (like Cursor background agents and Codex) runs in an isolated environment. Since Dart & Flutter are typically not present in the container, they need to be forcibly installed before starting work on a project. By declaring this in the initial prompt, we provide clearer instructions on how the agent should act, which enables it to complete the task with higher quality.

I hope this concept proves useful :-)

Please share your thoughts in the comments :-) This will help make this article visible to others and will be great support and motivation :-)

Thank you for your time and have a good day!
Anton

small thought: Developer Ethics may be a bridge to work with AI tools

Anton Malofeev — Thu, 15 May 2025 13:20:23 +0000

Last year, I intensely started using AI (LLM) tools and caught a terrible wave of sadness and melancholy after 5–6 months of use.

For me, the most difficult thing wasn’t that an LLM could write code in general, but the realization that, in fact, it’s not that important. A much more significant abstract question arose: why even write it if everything could change so quickly tomorrow that you wouldn’t even blink?

After feeling down and literally being sick of it, and wandering through bookstores, I stumbled upon an interesting book — “The Art of Excellent Products: Enchanting Customers with Premium Brand Experiences” by Riccardo Illy. And this book resonated so deeply that I understood how to resolve (for the time being) the moral dilemma with AI code, when you don’t write the code yourself, but AI does — through ethical principles.

In my opinion, ethical principles offer three possibilities:

Limitations or focus — by establishing principles, you can focus only on what is truly important and discard/deprioritize what does not align with these principles.
Flexibility in decision-making — knowing the limitations and having an ethical focus, you can, if necessary, make responsible decisions faster, but without sacrificing what is ethically important for the company/product.
Trust — having limitations in the form of chosen ethical principles, the values of the product/company can become more resilient to crises — which in the end can lead to more trust in the product for the end user. In theory :) Therefore, since the beginning of the year, I have started thinking about principles/values and trying to understand which ones are suitable — and why.

So I stepped away from digital to write by hand in a notebook. I’ve divided them into several groups, since I think they may change from the type of purpose.

I choose: Applications, Games, Personal Principles

For example for apps I came to:
— Convenience
— Simplicity
— Safety
— Longevity
— Usefulness

For games (since it’s my hobby, it a little different):
— Usefulness
— Creativity
— Fun
— Challenge

I feel they will change over time, but for a start it is enough.
Currently (May), the 5th month of testing — and I can honestly say that it has become much easier to focus on the problem and the solution than before. I am sure that a lot will change with the development of AI — but it seems like this could become a bridge for working with it from a moral and ethical standpoint (especially when you need to negotiate/choose between faster and better).

I hope this post inspires and proves useful in some way :-)
Please share your thoughts in the comments :-) this will help make this thread visible to others and will be great support and motivation :-)

Thank you for your time and have a good day!

Dart - applying zero objects and isEmpty pattern to everything

Anton Malofeev — Tue, 25 Mar 2025 22:18:46 +0000

It's more of a technical note, rather than an article, so I will try to express the idea more in a condensed and clear manner.

Before getting started, if your way to see how it works, I've recently uploaded small package - see it here.

Coming from the JS/TS world, when I first used Dart, the most fascinating thing among others was to use the isEmpty or isNotEmpty functions, and for strings, lists, maps, etc. It was amazingly simple, just not to write every time .length == 0.

Also, it was very useful to use empty/zero values like Duration.zero, Offset.zero, and many others that were a nice addition to this pattern.

Over time, I developed a habit to use the same principle for different cases and came to think, what if we use zero values for most cases, eliminating the need for null for most cases (not all, but nonetheless)? I searched and found that a similar pattern is used in Go, so I've started thinking:

Problem

imagine situation:

String? value;

// do something

value = "new value”;

What checks should we make to ensure the value exists to assign some value to a new variable?

final String newValue;
if(value != null && value.isEmpty){
  // do something
  newValue = “defaultValue”;
}  else {
  newValue = value;
}

What is the difference between null and isEmpty check in this situation?
What if we write

String value = “”;
final String newValue;

if(value.isEmpty){
  // do something
  newValue = “defaultValue”;
} else {
  newValue = value;
}

// use newValue

Nice but still verbose.
Would that be nice to use it inline? Let's try to rewrite it with a new extension:

extension StringX on String {
  String whenEmptyUse(String value) => isEmpty ? value : this;
}

final newValue = value.whenEmptyUse("defaultValue");

What if we try to apply it to lists, maps, values, and numbers?

extension ListX on List<T> {
  List<T> whenEmptyUse(List<T> values) => isEmpty ? values : this;
}

final newValues = values.whenEmptyUse(['defaultValue']);

extension DoubleX on double {
  bool isZero => this == 0;
  double whenZeroUse(final double value) => isZero ? value : this;
}

final opacity = 0;

final newOpacity = opacity.whenZeroUse(0.5);

This pattern is extremely useful with zero/empty values for objects too. For example:

class Person {
  const Person({this.name=''});
  final String name;

  static const empty = Person();

  bool get isEmpty => name.isEmpty;
  bool get isNotEmpty => name.isNotEmpty;
  // or use different names for to read nicer
  bool get isInitialized => name.isNotEmpty;
  bool get isNotInitialized => name.isEmpty;
}

extension PersonX on Person {
 Person whenEmptyUse(Person value) => isEmpty ? value : this;
}

Then we could use it everywhere the same simple way as checking a string:

var person = Person.empty;

// do something dangerous

final newPerson = person.whenEmptyUse(Person(name:'Frodo'));

We could do same for IDs, Lists with types, etc. etc..
This way we use simpler API, always know for sure that we have some value and we know how to identify default (empty, zero) value.

Hopefully it helps:)

Please don't forget to share your thoughts in comments:) it really helps the algorithms give this article to others to read, and it would be great support from you:)

Have a nice day!

Flutter app AI centric architecture for small startups. Part 2 — Stage 1 & 2

Anton Malofeev — Tue, 04 Feb 2025 22:19:11 +0000

Thoughts about scalable code structure based on developer as user philosophy combined with iterative design using AI.

Cover - Imaginary Gantt chart depicting astronomical growth and burnout:) Generated in leonardo.ai by feelings of building project.

Dev Architecture Series
Part 1 — Intro Notes — Previous
Part 2 — Stage 1 and 2 — You are here:)
Part 3 — Stage 3,4,5 and Conclusion Next
Part 4 — Libraries as Agentic Executables
Part 5 — Maintaining Libraries with AI Agents (planned)
Part 6 — Building Foundation with Open Source in mind (planned)
Part 7 — AI Project Bootstrapping (planned)
Part 8 — Storage Layer as Reliability Foundation (planned)
Part 9 — How to build for different Stores? (planned)
Part 10 — Dev Ethics as Dev Cornerstone (Decision Making) (planned)
Part 11 — Domain Knowledge (Agent Domain Context) (planned)
Part 12 — Building Tests with AI Agents (planned)

Introduction

In the first part of the series, we defined key terms and principles. If you didn’t checkout — check Part 1 — Intro Notes.

Let’s continue our journey!

Before get started — currently I’ve completed writing last part, but still need about a week to prepare it properly and publish. Thank you for your understanding.

Stage 1 — Prototyping.

Team: 1 (or at best 2) Developers
Main focus: develop fast and throw away every piece you don’t like as a ClientUser (or call it business).

Treat your repo as a workbench — you don’t know what will work, so expect multiple projects at the same time, even in different frameworks, different languages.

I suggest the following folder structure in that stage.

Abstract code structure

/
├── prototypes
│   ├── {prototype_name}
│   │   ├── idea.md  // This file contains the initial ideas and AI-generated insights for the prototype.
├── prompts
│   ├── agents
│   │   ├── {name}_agent.md  // Rules and guidelines for AI agents used in the project.
│   ├── ideas
│   │   ├── {idea}_gen.md  // Only AI-generated answers - ideas and prompts.
│   │   ├── {idea}.md  // Handwritten notes and domain knowledge. May include AI-generated answers too.

Example code structure

/
├── prototypes
│   ├── flutter/todo_with_amazing_animation
│   │   ├── idea.md
│   ├── typescript/yjs_prototype
│   │   ├── idea.md
│   ├── dart/frog_server
│   │   ├── idea.md
│   ├── just_cool_feature
│   │   ├── idea.md
├── prompts
│   ├── agents
│   │   ├── flutter_agent.md
│   │   ├── flutter_architector_agent.md
│   │   ├── rust_agent.md
│   ├── ideas
│   │   ├── charmed_animated_scroll_gen.md
│   │   ├── that_gradient_shader.md

If you don’t like the word prototype, use playground or experiments — this word is important because in later stages you will want to make sure that these pieces are playable, even for newcomers, but not movable, so your git commit will not explode xD

Every prototype should be as small as possible — it can be one to three files just to test and experience your idea.

I would advise not to set up strict lints for this stage to keep code as simple and small as possible, but in case you are testing them or using a new language — certainly go for it.

Stage 2 — Domain iterations.

Team: 1–2 Developers
Main focus: set up such an architecture that will support and help fast iterations in domains and do so.

The stage when you have at least one idea, and you are about to start development of the MVP (Minimum Viable Product).

And you iterate over and over domains to find the best (at this particular moment) experience for end users.

A note about linter rules

Strangely, just a couple of linter rules — and your path to create or eliminate your technical debt is set..

Choose your linter rules even before you look into the code, and choose wisely. These rules will affect not only you, but your AI-generated code, code quality, and technical debt as eventually, your codebase will grow, and if you decide to change just one rule, you may trigger a huge amount of linter warnings, errors, and team discussions.

UI Kit

This stage highly depends on the question — are you a completely lone developer, or a team with a designer, because the first thing to do is to create some, maybe not perfect, but usable ui_kit.

To make this, try to look into different techniques for organizing it. Personally, I prefer to use at least two steps from the Atomic Design methodology: atoms and molecules, but in my opinion, it highly depends on what you expect to achieve with the design, for what platforms the product is developing, etc. For one product, it can have only atoms and molecules. Another one — specific repeatable patterns for complex product cards, layout templates, pages templates, for another — Material, Human Guidelines, FluentUI approach (usually in that case, it is quite convenient to find official design in Figma or Sketch, etc.).

Treat it as a completely standalone library to not tie to any business requirements and focus on how it would be convenient to use, to develop, and maintain not only by you but by other developers and AI too.

Hopefully, to get it into the right words — that doesn’t mean it should be perfect, rather it should have well-documented READMEs around to explain the principles of how to create a new component of this library and make it useful.

From my experience, it is critically important how well you organize and define taxonomy, documentation, and convenience — this will affect any developer’s decision in the future, how fast you will be able to iterate (develop new, maintain, fix, and change old) for features, screens, etc.

UI Kit relations & workflow example

Then create the basic app code structure.

Abstract code structure

├── core // everything that is not API, data, state, and ui. May contain isolated business logic, but not tied to any specific domain.
│   ├── utils  // Utility functions, some duplicate isolated logic that is more related to the framework than the app, such as serialization, etc.
│   ├── extensions  // Extensions for types.
│   ├── hooks  // Optional hooks for logic duplication reduction. Usually handy for small portions of logic that are used in build methods.
│   ├── l10n  // Optional localization files.
│   ├── side_services  // Optional third-party services like Firebase, Analytics, etc.
├── data_local_api  // I use word API, as it is just shorter:) but it has the same meaning as services, sources). Prefer to treat it as your local backend server.
├── data_remote_api  // (services, sources) Remote APIs, preferably generated from backend schemas (REST or GraphQL or any other).
├── data_repositories  // (optional) Handles both local and remote APIs.
├── data_models
│   ├── api_dto  // (optional) Data Transfer Objects for APIs. Preferably generated for remote APIs, can be useful for local APIs too.
│   ├── {domain}_models  // (optional) Domain-specific models.
├── data_states  // Global level states for runtime data (notifiers, controllers, blocs, commands, etc.). Its purpose mostly to keep runtime data prepared to use in UI. These states can be used in all domains.
├── di  // Dependency injection setup (it may be provider, get_it, inherited_models, etc.). Will be available for all domains in the app. Here you can set up API, states + methods to initialize them and use in `ui_root`.
├── ui_root  // Place here everything that is needed for the app to start: bootstrap methods, data_state and side_services initialization, error catching (Firebase, Sentry), Analytics, etc.
├── ui_kit // uses below two Atomic Design principles: atoms and molecules, but you can use any other principles, such as Material, Human Guidelines, FluentUI, etc.
│   ├── UI_KIT_README.md  // Short Rules and main principles defining how and why you made certain choices in underlying structure and links to the underlying READMEs. The last part is important, because as I found out, AI tools like to use README for designing or development.
│   ├── atoms
│   │   ├── ATOM_README.md  // Domain knowledge for atoms.
│   ├── molecules
│   │   ├── MOLECULE_README.md  // Domain knowledge for molecules.
├── ui_{domain} // all ui domains
│   ├── {DOMAIN}_KNOWLEDGE.md  // Domain knowledge for the specific UI domain.
│   ├── {flow} // one or more screens or views united into one flow. Every flow has one entry point screen (or at least one) and every screen has one or more features.
│   │   ├── {flow}_screen.dart  // Entry point for the flow.
│   │   ├── {feature_name}  // Domain and flow-specific features.
├── envs.dart  // [Environment variables](https://codewithandrea.com/tips/dart-define-from-file-env-json/)
├── router.dart  // Your preferred router setup with defined routes
├── {platform}_app.dart  // Entry point for the platform-specific app.
├── common_imports.dart  // Optional. Place here all imports that are used in the whole app. Also, it is handy to place here all exports from barrel files from each top folder.

And finally, create domains ui{domains}_ which will include the most critical app experience and iterate over them.

A note about UI Domains

Schematic example of what can be shared, and what — can’t inside domains.

Inside domain, you may work with different types of data layer, screen states, widget states (in Flutter it is called Ephemeral state), some business logic, specific to feature models which you never intend to share with other domains.

I suggest a small decision to manage relations between domains — reuse only widgets (flows, screens, features), do not share/reuse data. If you need to share something from domain local data layer — move it to global data layer, from which it will be available for all domains. For example, a local model may go to data_models, screen state maybe refactored and go to data_states.

A word about data_states — Flutter documentation calls it App State. In other words, you can define it as global-level states for runtime data (notifiers, controllers, blocs, commands, etc.). Its purpose is mostly to keep runtime data prepared to use in UI. These states can be used in all domains.

Now let’s move back to global project structure.

Relations between global layers

Option 1 — with common_imports

Basic app relationships diagram using common imports for any ui domains folder

Option 2 — without common_imports

Basic app relationships diagram without using common imports for any ui domains folder

Note. Barrel File.

I find it very convenient to create barrel files on each top folder by exporting underlying classes in the same manner as Dart does for package export https://dart.dev/tools/pub/create-packages. This makes future refactoring easier and gives the ability to not mess with git changes when some file moves later.

Also, this practice makes it easier to think of all global folders as packages / libraries which are independent and may change their content, internal structure, but will maintain consistency with their external API.

At the same time, currently I have no experience in how it affects the ability of deferred imports. https://dart.dev/language/libraries#lazily-loading-a-library I think at least you may expect that it will have no effect on this stage, but since it is a way to load libraries — it may become more effective with stage 4.

Second note. Domain Knowledge

UI Domain relations & workflow example

Optionally, I recommend trying to place in all data and ui layer folders a Domain Knowledge file. It should be simple enough to regenerate and iterate with AI — this may give you context to work with particular domain features, develop, or maintain.

Semantically, to make it easy to get this context and navigate, it would be great if you align it with the above folder’s name, for example, if the folder above is ui_guide, then below you may place a file UI_GUIDE_CONTEXT.md or UI_GUIDE_KNOWLEDGE.md. The reason is simple: when you use file search — you will be able to quickly find this file, when you communicate with AI tool — you will much faster find required context.

Now let’s take a note on semantics.

Visual representation of layers separation, its relations and building order

First, the whole data layer has a prefix data for two reasons:

to keep it at the top of the lib folder, so we could easily access it
to keep always in mind that it is a data layer only

Second, domains (or UI layer) have a prefix ui. This makes this layer

on visual and physical distance from the data layer
stack all ui related domains together.

While it may seem an over-engineering attempt, defining the organization of data and ui layers visually distinctive from each other, will affect how you develop your application, because you will see it differently — more from an end-user perspective.

Finally, let’s summarize all words into graphics:

Abstract code structure

/
├── pubspec.yaml  // <- define workspace to use the whole space as monorepo https://dart.dev/tools/pub/workspaces
├── apps/
│   └── {platform}_app/  // <- platform can be replaced by your first target platform, for example mobile_app
│       ├── core/
│       │   ├── core.dart
│       │   ├── utils/
│       │   ├── extensions/
│       │   ├── hooks/
│       │   ├── l10n/
│       │   └── services/
│       ├── data_local_api/
│       ├── data_remote_api/
│       ├── data_repositories/
│       ├── data_models/
│       │   ├── api_dto/
│       │   └── {domain}_models/
│       ├── data_states/
│       ├── di/
│       ├── ui_root/
│       ├── ui_kit/
│       │   ├── ui_kit.dart  // <- place ui kit initially as a folder of mobile_app to keep initial simplicity
│       │   ├── UI_KIT_README.md
│       │   ├── atoms/
│       │   │   └── ATOM_README.md
│       │   └── molecules/
│       │       └── MOLECULES_README.md
│       ├── ui_{domain}/
│       │   ├── {DOMAIN}_KNOWLEDGE.md
│       │   ├── {flow}/
│       │   │   └── {feature_name}/
│       ├── envs.dart
│       ├── router.dart
│       ├── common_imports.dart
│       └── {platform}_app.dart
└── prototypes/
    └── {prototype_name}/
        └── idea.md  // This file contains the initial ideas and AI-generated insights for the prototype.
    └── prompts/
        ├── agents/
        │   └── {name}_agent.md
        └── ideas/
            ├── {idea}_gen.md
            └── {idea}.md

Example code structure

/
├── pubspec.yaml
├── apps/
│   └── mobile_app/
│       ├── core/
│       │   ├── core.dart
│       │   ├── utils/
│       │   ├── extensions/
│       │   ├── hooks/
│       │   ├── l10n/
│       │   └── services/
│       ├── data_local_api/
│       ├── data_remote_api/
│       ├── data_repositories/
│       ├── data_models/
│       │   ├── data_models.dart
│       │   ├── api_dto/
│       │   ├── payments_models/
│       │   ├── chat_models/
│       │   └── profile_models/
│       ├── data_states/
│       │   ├── data_states.dart
│       │   ├── app_settings_notifier.dart
│       │   └── user_profile_cubit.dart
│       ├── di/
│       │   ├── di.dart
│       │   ├── dependency_injector.dart
│       │   ├── global_initializer.dart
│       │   ├── global_state_initializer.dart
│       │   └── global_state_providers.dart
│       ├── ui_root/
│       │   ├── ui_root.dart
│       │   ├── app_scaffold.dart
│       │   └── bootstrap.dart
│       ├── ui_kit/
│       │   ├── ui_kit.dart
│       │   ├── UI_KIT_README.md
│       │   ├── atoms/
│       │   │   ├── atoms.dart
│       │   │   ├── ATOM_README.md
│       │   │   ├── ui_text_field.dart
│       │   │   ├── ui_icon.dart
│       │   │   └── ui_badge.dart
│       │   └── molecules/
│       │       ├── molecules.dart
│       │       ├── MOLECULES_README.md
│       │       ├── ui_search_field.dart
│       │       ├── ui_app_bar.dart
│       │       └── ui_animated_grid.dart
│       ├── ui_payments/
│       │   ├── ui_payments.dart
│       │   ├── PAYMENTS_KNOWLEDGE.md
│       │   ├── transactions_flow/
│       │   │   ├── transactions_screen.dart
│       │   │   ├── features/ // consider making this name adaptive; if a screen lacks features, it may not need them. If features are complex, naming them may be more efficient than grouping them.
│       │   │   │   ├── transactions_list.dart
│       │   │   │   └── edit_transaction_popup.dart
│       │   └── pay/
│       │       ├── pay_screen.dart
│       │       ├── qr_pay/
│       │       │   ├── *
│       │       │   └── qr_pay_feature.dart
│       │       ├── provider_pay/
│       │       │   ├── *
│       │       │   └── provider_pay.dart
│       │       └── crypto_provider_pay/
│       │           ├── *
│       │           └── crypto_provider_pay.dart
│       ├── ui_profile/
│       │   ├── ui_profile.dart
│       │   ├── PROFILE_KNOWLEDGE.md
│       │   ├── auth/
│       │   └── settings/
│       ├── envs.dart
│       ├── router.dart
│       └── mobile_app.dart
└── prototypes/
    ├── flutter/todo_with_amazing_animation/
    │   └── idea.md
    ├── typescript_yjs_prototype/
    │   └── idea.md
    ├── dart_frog_server/
    │   └── idea.md
    └── just_cool_feature/
        └── idea.md
/prompts/
├── agents/
│   ├── flutter_agent.md
│   ├── flutter_architector_agent.md
│   └── rust_agent.md
└── ideas/
    ├── charmed_animated_scroll_gen.md
    └── that_gradient_shader.md

Personally, I find it difficult to nest flows too deep, so there we have two choices:

when the flow becomes too huge or feels logically complete — it seems more convenient to acknowledge it as a domain and move it on a global level as a domain.
or break this flow into several flows, if it feels there is too much different functionality in one place.

I think the most important part of this stage is to accumulate enough Domain Knowledge before diving too deep into endless features.

Stage 3 — Feature iterations.

Team: 2 Developers
Main focus: test and try features for specific domains to make these domains logically complete.

While this part is quite small for changes — and may not contain any radical changes in structure, I think it’s quite important on this stage to follow two principles:

Keep refreshing, refining, and updating domain knowledge from testing and using the application.
Keep every small feature implementation separate from the screen where it is placed. Treat the screen as a layout where you place widgets, and it would be much easier to reuse any feature-related widgets, as they will behave as self-contained micro applications.

This ends the first three stages of thoughts about scalable architecture approach.

Thank you for your time, to continue, use a link below.

Please don’t forget to share your thoughts in comments:) it really helps the algorithms give this article to others to read, and it would be great support from you:)

Next -> Stage 3,4,5 and Conclusion

DEV Community: Anton Malofeev

Thoughts about tooling | progress on semantic intents

code is a "translation" | after 1.5 years of "vibe-coding" adventures thoughts

FAQ-driven development 😃 - or new old way to write docs / rules / prompts

FAQ as Natural Knowledge Compression

Structuring FAQs: The WHY vs HOW Pattern

DESIGN_FAQ.md: The WHY

DX_FAQ.md: The HOW (DX - Developer Experience)

When to use both

AI Agent Rules

HARD Skull / Rule create the FAQ xD

Docs

Specs

Use it even in Code Comments too!/) commentart:)

Reimagine Libraries management as Apps using Agentic Executable framework

Libraries as Agentic Executables

Why (The Problem)

How (The Solution)

Working principles:

Core Principles

Core Idea

Implementation Architecture

Workflow Overview

Installation workflow example:

Library Author workflow:

How to use it Today?

You are Developer:

You are Library Author | Maintainer:

Conclusion

Links:

How to conduct a useful technical interview (based on my personal experience (subjective opinion))

Flutter app AI centric architecture for small startups. Part 3 - Stages 3–5

Introduction

Stage 3 — Feature Iterations

Stage 4 — Scaling

Path 1 — Scaling to Other Platforms

Path 2 — Same App, Different Configurations

Stage 5 — Scaling Application Domains

Conclusion

Flutter 💙 Cursor: setting up Background Agent

Ethical AI Dev Manifesto

Flutter 💙 Jules (setting up container for background AI Agent)

Why is this important?

small thought: Developer Ethics may be a bridge to work with AI tools

Dart - applying zero objects and isEmpty pattern to everything

Problem

Flutter app AI centric architecture for small startups. Part 2 — Stage 1 & 2

Introduction

Stage 1 — Prototyping.

Stage 2 — Domain iterations.

Stage 3 — Feature iterations.