DEV Community: Mark Parker

MajorDom — Your Effortlessly Simple Smart Home, Launched on Kickstarter

Mark Parker — Thu, 03 Oct 2024 19:29:23 +0000

Automate routines, save energy, and enjoy hands-free control with ease.
Secure, private, open source.

What is Smart Home

A true smart home is a system that provides comfort, security, and energy efficiency autonomously. While some actions are easier to control via smartphone or voice command, most should work without user intervention. That’s what MajorDom is — a truly smart home that works autonomously in the background.

Benefits of Smart Home

Automate routines: Dim lights at bedtime, adjust the thermostat when you leave, and lock doors at — all automatically.
Optimise energy: Cut down on energy waste by turning off lights in empty rooms and adjusting HVAC based on occupancy and weather conditions.
Peace of Mind: Get real-time alerts for leaks, fires, break-ins, or when your washing machine finishes — monitor everything from your phone, anywhere.
Vacation mode: Automate lights and TV to make it look like someone’s home while you’re away, with security fully active.
Remote control: Check if you left the lights on or the door unlocked from anywhere in the world, and adjust your home’s temperature remotely for a warm welcome.
Intercom: Send voice messages to all speakers in your home.
Personalised assistant: Receive spoken notifications, set custom alerts, control your home hands-free, and manage lists, calendars, and more without touching your phone.
And many more: Imagine a custom movie night scene that dims lights, lowers blinds, and sets up your sound system—all with a single voice command.

The Best of Both Worlds: Usability and Functionality

Vendor products often limit functionality, while popular open-source systems are overwhelming. MajorDom offers the best of both worlds—a plug-and-play solution with no compromises.

MajorDom Makes Home Automation Really Simple

We believe technology should be available to everyone. While smart homes have traditionally had a high entry barrier, MajorDom is here to change that. It’s not only simple to use but, more importantly, simple to start with — making home automation accessible to tech enthusiasts, families, kids, and even complete non-tech-savvy beginners.

Complete Plug&Play Solution

Unlike other open-source platforms, MajorDom offers both hardware and software, delivering a truly comprehensive plug-and-play experience.

Easy as a Game

Getting started is easy — no lengthy preparation or complicated installation required. It’s like playing a game with levels. Start with MajorDom Hub and MajorDom Audio, and our app will guide you step by step on your journey to a smarter home.

Intuitive and Friendly Interface

MajorDom provides a single app for everything, with a simple and user-friendly interface. No need for complicated dashboards with tons of graphs and charts — this is your home, not a spaceship. Check your home’s status at a glance, control devices, and set up scenes and automations with ease. Your digital majordomo handles everything else.

Vendor Unlock and Wide Device Support

It's all about freedom. Vendors lock users in their ecosystems, so you can't use a device of another brand. But MajorDom breaks those barriers. There are many protocols, and the good thing is that MajorDom can handle all of them: WiFi, Bluetooth, Matter, ZigBee, Z-Wave-whatever. It even detects most devices automatically for easy pairing. Pick any, it just works. And even if you found an extremely rare device that doesn't — don't worry, either our team or the open source community will fix it soon.

Family and Guests Ready

MajorDom is designed to be intuitive for everyone. You can easily share access with family and guests while maintaining full control. But automations handle most tasks in the background, ensuring that everyone can enjoy the convenience without needing to manage it themselves.

MajorDom Makes Home Truly Smart

Automations

In MajorDom, you can set up any scenario with ease in a few taps. Or just describe your idea and let Archie do the work. If you’re unsure, add all your devices and check the suggestions section. It doesn’t just analyze your devices; it learns your habits and patterns for better recommendations. You can even allow it to add scenes and automations without confirmation for an even more magical experience. We call it Smart Automations.

Meet Archie: Your Personal Assistant

Archie, your personalized voice assistant, listens in multiple languages, understands complex contexts, and handles multiple commands in a single request. But Archie isn’t just for controlling your home — it manages your day-to-day tasks, provides information, and integrates seamlessly with your calendar, reminders, notes, contacts, and more. Powered by large language models, Archie’s skills are limitless. Top of the line.

Archie embodies MajorDom's core values: privacy, autonomy, plugins, and user-friendliness. It operates entirely on-device, but internet expands its possibilities even further.

MajorDom — Smart Home that is Actually Reliable

Privacy at the Core

All current vendor products operate through the cloud and, what's more, are owned by the same companies that profit from selling user data, running ads, or hosting marketplaces. In contrast, we’re convinced that privacy and security must be foundational. That’s why MajorDom stores all data locally and processes it on-device. For remote control, communication is end-to-end encrypted, ensuring that only you can access your home. With MajorDom, your data remains yours.

Always On, Even Offline

Another advantage of on-device processing — it doesn’t rely on the internet. No matter what happens to the cloud or your internet provider, your home stays smart, as if nothing happened.

Ownership, Not Renting

Since you own the hardware and the software runs entirely on-device, you’re always in control of your home and your data. It’s about ownership, not renting. Your home — your rules.

MajorDom Is Open in Every Way

Open Source Transparency

MajorDom is built on open-source technology, ensuring complete transparency. You can see, trust, and even customize every part of your smart home system. Transparency is at the core of our commitment to your privacy and security.

Open for Innovations: Meet Idea Forge

We want to make it as easy as possible for people to integrate their ideas — whether hardware or software. That’s why we created the ‘Idea Forge.’ This platform transforms user proposals into practical features. Anyone can submit ideas through the suggestion form — no coding required, just a spark of innovation.

These suggestions then appear on a community voting board, allowing everyone to influence the development process. Democracy in action.

Open for Extensions and Customizations

But it’s not just a waiting game. If you’re feeling adventurous or just can’t wait, roll up your sleeves and code any feature yourself. You contribute, you create, and who knows — you might just end up part of the MajorDom team.

MajorDom’s plugin system makes this even easier — any community-built feature can be installed directly through the UI. Developers can implement their ideas as plugins or propose them for integration into MajorDom’s core via merge requests.

Open for ALL Devices (DIY Friendly)

It’s not just about unlocking support for devices from all brands and manufacturers. With MajorDom, you can integrate anything as a fully functional smart home accessory in just minutes: from your Raspberry Pi to an Arduino. For example, imagine customizing LED lights or automating plant watering.

Rewards

MajorDom Hub

The heart of your smart home, seamlessly connecting and supporting a wide range of accessories.

MajorDom Audio

A smart speaker with built-in Archie, our advanced voice assistant, ready to assist you in every aspect of your smart home.

Limited-Edition Merch

Let's be closer. Originally created for our team to celebrate our first anniversary, we’ve decided to share a bit of our spirit with you too <3
(Available only through the Kickstarter campaign)

Stretch Goals: Unlock More Features Together!

We’d love to give you everything right from the start, but quality takes time, and every feature requires resources. That’s why we’ve set stretch goals — to ensure we can deliver the best possible experience without compromising on what makes MajorDom great. So, share this page with your friends, family, and everyone who might be interested. The more the campaign raise, the more features everyone gets to enjoy. It’s a win-win for all of us! Let’s build the future of smart homes together.

60k MajorDom Hub & Audio, Smartphone App, and all features that aren't mentioned bellow
80k Home Screen Widgets
100k Idea Forge
150k Tablet / iPad App
200k Access Sharing
300k Smartwatch (wearable) App
400k Documented SDKs for plugins, apps, and DIY devices
500k App (Plugin) Store
600k Cameras support
700k On-device LLM
800k SubGHz and IR devices support
1m+ Customizable Voice for Archie

*Merch has it's own stretch goals: we need to have at lest 50 orders of the item to be able to produce it with reasonable price.

Roadmap

Shipping and Taxes

MajorDom will be shipped worldwide.

Shipping will be charged via our pledge manager after the campaign, where you will also be able to confirm your rewards, address, and choose extra add-ons. Please note, that our prices do not include local taxes, duties, and VAT, that will be subject to the laws and regulations of each individual country.

Summary

Privacy-first design, open source, intuitive interface, wide device support, friendly game-like setup, smart automations that adapt to your habbits, and Archie—the best-in-class personal voice assistant. Plus, exclusive merch. So, why wait?

Join the smart home revolution today!

Start Simple: Begin with the Hub and Audio to explore the possibilities as you go. You’ll have a strong foundation for your smart home and immediate access to the best voice assistant around. Follow the app’s step-by-step guides to make your home smart at your own pace.
Limited-Time Offer: Kickstarter discounts are a one-time deal — don’t miss out!
Perfect Gift: MajorDom makes a great gift, bringing smart home convenience to your loved ones.

Back MajorDom on Kickstarter today and make your home truly smart!

Meet MajorDom: a smart home of the future that is really smart

Mark Parker — Fri, 31 May 2024 01:05:00 +0000

MajorDom - a brand new open-source smart home ecosystem, built for privacy, autonomy, and wide device support. The platform combines intelligent automations with easy plug-n-play design and a really smart voice assistant.

In the world of smart homes, you often have to choose between usability and functionality. Thinking about what an ideal smart home could be, we came up with the idea of MajorDom — a system that seeks to change this balance and simplify life without sacrifice. In this post, we'll share our vision and some core principles of the new ecosystem, including privacy, autonomy, and broad device support.

Gadgets

Today there are many different gadgets for the home: lamps, curtains, heaters, vacuum cleaners, security, and microclimate sensors. They are designed to make life easier, but not everything is so simple.

Previously, each device had its own control protocol, its own standards, its own security methods, and each of them needed a separate application. The more devices there are in the house, the more time you need to devote to managing them, which turns into a new routine. It's like juggling too many balls.

Current solutions

Smart home (or home automation) systems were supposed to solve this problem, but they are still far from ideal. There are two types of such systems: proprietary from digital corporations and popular open source. Unfortunately, both of them have disadvantages. I propose to draw up a graph in which the ease of use of complex to simple ones will be on the x axis, and the smartness and functionality of the system will be on the y axis.

It turns out that all proprietary systems are located somewhere in the center-bottom. They provide some functionality that the average person can handle after spending some time learning. Most often, these systems are closed and support only their limited list of devices in their special application. Their functionality boils down to replacing the physical switch with a button on the phone or simple voice commands. Sometimes there are elementary automations, or rather scripts that need to be written manually.

At the same time, they are too dependent on cloud solutions. A server failure, changes in geopolitics, new regulations, or a simple lack of Internet means a smart home shutdown.

But what’s worse is that the most popular systems belong to advertising or marketplace giants who make money by selling users’ personal data. This is the basis of their business model, which is why they cannot change, so trust and privacy are out of the question.

Those who want more features or don't want surveillance have to switch to open solutions and pay for it with the complexity of configuration and installation. This is the area above and to the left of center, but often it's worth it. Open systems offer more freedom, integration with almost any device and protocol (thanks to plugins), unlimited customization and full control. This is a task for techies who want to spend their evenings studying forums and developing their own configurations. Likewise, some people like to spend hours in the garage going through all the parts of the car. I'm not saying it's bad, everybody deserves a hobby, but most people want a car just to drive it. Of course, you can hire a professional to handle all the devices for a fortune. But what if you don't want to hire a professional or become one yourself?

We want to make a system that will occupy the upper right corner: it will work right out of the box, support a wide range of devices, securely store user data, and at the same time be smarter and more functional than the rest.

Smart home ecosystem

Let's talk about how smart home ecosystems work and how they differ from home automation systems. It all starts with devices that directly control the house: lamps, relays, modules with a motor. This is the first "physical" layer. The second layer is for interface, mobile apps, voice assistants, etc.; let's call it "application" layer. Now, let's connect them via wifi or bluetooth.

But let's imagine that we have several devices, and each one has an app. Doesn't look very comfortable, does it?

Now we will transfer the devices to more energy-efficient radio protocols. But how now to connect them to your smartphone? Let's add an intermediary in the form of a hub, which has a radio module on one side and the same wifi on the other. As a bonus, we will connect all devices from the same manufacturer to it. Now each app can control a few devices, but only produced by the same brand. This is what closed “ecosystems” look like. Each uses its own protocols and standards, so they are not compatible with each other.

But what’s worse is that not all applications can communicate with the hub directly within a local network (LAN) and use the server even when you are at home. This is the case when turning off the Internet means a complete blackout, while turning on means remote control of the home from the cloud (do you trust the cloud of a company that makes money from selling your personal data but doesn't care about keeping it safe?)

To fix this, we’ll replace the proprietary hub with a raspberry pi with some open source home automation system, and also add plugins for device integration. This makes it possible to combine all devices into one system, for example to program global automations or advanced scenarios. It's better, but one little thing called the interface is missing.

Fortunately, some open source solutions come with a web frontend or even a mobile application (not always user-friendly). By adding a couple more plugins, we can forward some devices (or all, if we are very lucky) of the devices to an application of one of the ecosystems. In this case, the hub acts as an intermediary or adapter for third-party devices. But now we are dependent on this ecosystem and receive all its disadvantages, which were discussed at the beginning of the article. Alternatively, we can connect another plugin with for a custom or 3rd-party cloud solution, but this becomes either too complicated or still not secure enough.

I would like to note that it is not always possible to completely replace a proprietary hub with a custom one. Often you will need to have both hubs (proprietary and custom) for the system to work and support required devices and applications. This could end up becoming a tangle of technology. In short, it's too complicated, and it's not worth it.

By the way, this example reminds me of something:

So we have 4 layers: devices, hub (automation, software control), servers, interface (apps, voice assistants, etc.). The ecosystem is all 4 layers and their connection, not just one. To make everything work perfectly, we don't just do one of the layers, for example an automation system at the hub level. We do all three top levels: app, voice assistant, cloud, and hub with maximum support for third-party devices, thus maximizing compatibility and integration of the whole system out of the box: autonomous, private, independent and secure. This is MajorDom.

Why our ecosystem is smarter: our philosophy

We lay the following principles as the foundation of our work:

Complete privacy of personal data — home is not a place for prying eyes. Privacy is a basic right of every user.
Autonomy — maximum independence from the outside world, disconnected Internet should not be a problem
Ease of setup and use — technology should serve people, and not vice versa. It's fine to dive deep into hobbies, but many just need something that works right out of the box.
Maximum support for different devices, protocols, and integrations — in addition to the previous point
No artificial restrictions — avoid being Apple and give the opportunity for deep configuration and customization to those who require it.

We make a completely private, fully autonomous, truly SMART home that is different to the options promoted by big tech. We are convinced that privacy is not just something abstract, not even a promise. Privacy — is your core right. And we believe that technology must work for you, not the other way around.
No sacrifices, no exceptions.

So, we are going to reinvent the smart home. In our vision, a true smart home has an invisible army of devices, that are working autonomously in the background, improving your everyday life and covering your back. It's like having a digital majordomo.

A true smart home must be independent from the outside world. No failures because the internet or a random server is down. It's a fully autonomous ecosystem that doesn't require anything else, either: not internet, not cloud services, and not even a human.

At the same time, a system must be simple to use. No long installations or configurations. No periodical change of settings. No code writing. Just plug and play. Technology must work for you, remember?

How: Architecture design

But, how do we do it? First things first, the system needs a name. We called the system MajorDom. And it perfectly fits the description.

Privacy Implementation

But how we deal with the most important thing — your data?

While all other systems are black boxes, we believe that MajorDom must be open source, so there is no behind-the-scenes manipulation and anyone can open and read it, highlight issues, suggest changes, or even contribute to it.

While the source code is publicly available, your data is protected like never before. Let’s talk about some technical solutions MajorDom utilizes.

To make the system private and autonomous, most of the data is stored locally on the devices and generally on the Hub. This guarantees privacy, and since all data is stored locally, automations and all the other features work perfectly even in the absence of the Internet. This is unlike other systems, which always rely on the internet connection because all data is sent and stored somewhere on the server. We have no 3rd-party services, no extra transfers, no data collectors.

But in some cases data must be transferred though the internet, for example with remote control when you're on the go. In this case, data is securely end-to-end encrypted and keys are stored only on user’s physical devices. That means you can actually access all of your accessories remotely, only you, and absolutely no one else, including admins and developers.

Supported Devices: Matter, Merlin.

Of course, before setting up automation, you need devices in the house. The Zigbee Alliance, renamed the Connectivity Standards Alliance or CSA, is a coalition of various smart home companies that have decided to create a universal communication protocol for all home automation devices. They called this protocol Matter. And MajorDom is compatible with it. This means you can add any Matter compatible device to your MajorDom system. And that is not all.

Matter natively only supports the most common underlying devices, which is why we created the Merlin communication protocol. Thanks to a more flexible architecture, it not only significantly expands the list of supported devices, but also makes it endless.

At the same time, we understand that today only a small portion of devices already released support one of these protocols, so we are also going to add integrations of devices using zigbee, z-wave, wifi and BLE, thus becoming the most universal ecosystem.

Interface

Now, how are we going to communicate with this? For this task, we designed a beautiful application, with customizable themes. It's a real pleasure to use. And it's available for all major platforms: android, including smartphones, tablets, and watches, and iOS family with iPhones, iPads, Macs, Watches, tvOS, and even future visionOS. The app also includes widgets that you can add to your desktop, home, or lock screen with any supported device, so you can access your home even without launching the app. We have ensured that full control of your home is always at your fingertips.

But a truly smart home must work autonomously most of the time, in the background, so you don't even notice it. Now, how are we going to automate this? Write scripts, like every other system, right? We’re going to use scripts? No. Nobody wants to write scripts. And we know this. Instead of this:

For automations, we added the second amazing tab to the app, which helps you set up any scenario with ease.

To simplify the process even more, we invented a smart suggestions technology that predicts what you want to automate. And sometimes it's so smart, so it even doesn't require the user’s help. For instance, you can just add all accessories and start using them without adding any automation or scenario. After a short time, this technology will suggest scenes and automations based on your habits. You can even allow it to add scenes and automations without confirmation in the background. It's that easy. And it's phenomenal. It works like magic. We called this technology Smart Automation.

Archie — a Smart Voice Assistant

Automations are good for everyday routine. But sometimes you need a more personal touch that's more than just commands and controls.

Archie, the Autonomous Responsive Cognitive Home Interaction Engine. The voice assistant that outsmarts all others and really understands you. Archie is able to understand what you need to an extremely high level of precision and makes communication effortless by offering a live language experience that feels spontaneous and conversational. Top of the line.

Like a truly professional majordomo, Archie speaks many languages. He can simultaneously listen to up to three preselected languages.

But Archie isn't just for controlling your home; it's for every facet of your daily life, from managing tasks to providing general information.

Archie inherits all the core values of MajorDom: private, autonomous, easy to use, and truly smart. Archie can work completely offline, but the Internet expands its possibilities to an unlimited range. Powered by the largest language models, Archie's skills are closer to real artificial intelligence than ever before in human history.

Work out of the box: we make our own devices

“People who are serious about software should make their own hardware” — this quote is especially relevant for a smart home. This is the only way to ensure seamless integration of multiple protocols out of the box. The same goes for the assistant: not every platform can handle offline speech recognition, processing, and synthesis. In addition, you can completely trust it only when you know that there are no third-party software on the device with access to the microphone. That's why we're developing two of our own: MajorDom Hub for device management, automation; a portal to the ecosystem — like the hands of the home. And MajorDom Audio — a smart speaker for Archie; the ears and voice of the home.

One last thing… for Contributors.

We want to make it as easy as possible for people to integrate their ideas — whether hardware or software. To this end, we have created two major tools to allow everybody to become a contributor.

First, in the development of MajorDom, we've established the 'Idea Forge'. This platform transforms user proposals into practical features. Anyone can submit ideas through the idea suggestion form. You don't need to be a coder; you just need a spark of innovation. These suggestions then appear on a community voting board, allowing everyone to influence the development process. Democracy in action. The most popular ideas are considered for implementation by the MajorDom Team. This isn't just about users; it's about turning users into makers.

But it's not just a waiting game. If you're feeling adventurous, or you just can't wait, you can roll up your sleeves and code any feature yourself. You contribute, you create, and who knows, you might just end up part of the MajorDom team.

Secondly, we are simplifying the job for all developers. We build modular hub firmware with plugin support and convenient libraries with detailed documentation.

Conclusion

At the moment, the project is still under active development, but most of what is mentioned has already been implemented, including the core of the system, integration of some protocols, remote control, automations, the offline part of Archie and the mobile app. We will publish further news here, but I also recommend subscribing to the relevant project pages on social networks. Sign up for early access at majordom.io

Join the project

The project is quite complex and large-scale, and a high-quality result requires many hours of work by professional engineers, programmers and designers. In the modern capitalist world, only commercial development can guarantee a stable result.

Pre-orders, Kickstarter, Donations

In the future, the project will be published on Kickstarter — a crowdfunding platform on which it will be possible to place the earliest pre-orders of devices, but you already can financially support the project on patreon or buymeacoffee.

Become part of the team

Our team already has designers, software engineers for the frontend, backend, mobile apps, the Hub, and the voice assistant. At the same time, we are looking for industrial designers, embedded hardware engineers, as well as programmers who understand the low-level details of popular protocols in the smart home field. If you are doing something else, but want to join the project, write your suggestions, everyone is welcome.

Investors

We are also considering receiving investment from a $50k pre-seed round for a share of the company. Speaking of numbers, the current smart home market is valued at US$100 billion, with a projected growth of up to US$600 billion in 2033. Looks like a great investment opportunity.

Contacts

Telegram: t.me/MarkParker5
Email: mark@parker-programs.com

Python Architecture Essentials: Building Scalable and Clean Application for Juniors

Mark Parker — Tue, 28 May 2024 22:00:00 +0000

Structuring a project with SOLID, KISS, DRY, and clean code principles, along with efficient design patterns. In simple words with real examples.

Dive into the fundamentals of scalable and clean application architecture in Python with this beginner-friendly guide. Here, we explore essential concepts such as Object-Oriented Programming (OOP), SOLID principles, Dependency Injection (DI), and typing. This article is designed to take you from zero to hero, transforming complex architectural standards into actionable insights that enhance modularity, low coupling, and high cohesion. Through practical examples, you'll learn how to develop multilayered architectures that ensure modularity and independence, preparing you for successful, maintainable projects.

Some Clean Code Theory

Before diving into architecture, I would like to answer a few frequently asked questions:

What are the benefits of specifying types in Python?
What are the reasons for splitting an app into layers?
What are the advantages of using OOP?
What are the drawbacks of using global variables or singletons?

Feel free to skip the theory sections if you already know the answers and jump directly to the "Building the App" section.

Always Annotate Types

Annotating all types in Python significantly enhances your code by increasing its clarity, robustness, and maintainability:

Type Safety: Type annotations help catch type mismatches early, reducing bugs and ensuring your code behaves as expected.
Self-documenting Code: Type hints increase the readability of your code and act as built-in documentation, clarifying the expected input and output data types of functions.
Improved Code Quality: Employing type hints encourages better design and architecture, promoting thoughtful planning and implementation of data structures and interfaces.
Enhanced Tool Support: Tools like mypy utilize type annotations for static type checking, identifying potential errors before runtime, thus enhancing the development process.
Support from Modern Libraries: Libraries such as FastAPI and Pydantic leverage type annotations to provide functionalities like automatic data validation, schema generation, and comprehensive API documentation.
Advantages of Typed Dataclasses Over Simple Data Structures: Typed dataclasses improve readability, structured data handling, and type safety compared to dicts and tuples. They use attributes instead of string keys, which minimizes errors due to typos and improves code autocompletion. Dataclasses also provide clear definitions of data structures, support default values, and simplify code maintenance and debugging.

Why Do We Need to Split the App Into Layers

Splitting an application into layers enhances maintainability, scalability, and flexibility. Key reasons for this strategy include:

Separation of concerns

Each layer focuses on a specific aspect, which simplifies development, debugging and maintenance. #### Reusability
Layers can be reused in different parts of the application or in other projects. Code duplication is eliminated. #### Scalability
Allows different layers to scale independently of each other depending on needs. #### Serviceability
Simplifies maintenance by localizing common functions in separate layers. #### Improved collaboration
Teams can work on different layers independently. #### Flexibility and adaptability
Changes in technology or design can be implemented in specific layers. Only the affected layers need to be adapted, the others remain unaffected. #### Testability
Each layer can be tested independently, simplifying unit testing and debugging.

Adopting a layered architecture offers significant advantages in development speed, operational management, and long-term maintenance, making systems more robust, manageable, and adaptable to change.

Global Constants vs Injected Parameters

When developing software, the choice between using global constants and employing dependency injection (DI) can significantly impact the flexibility, maintainability, and scalability of applications. This analysis delves into the drawbacks of global constants and contrasts them with the advantages provided by dependency injection.

Global Constants

Fixed Configuration: Global constants are static and cannot dynamically adapt to different environments or requirements without modifying the codebase. This rigidity limits their utility across diverse operational scenarios.
Limited Testing Scope: Testing becomes challenging with global constants as they are not easily overridden. Developers might need to alter the global state or employ complex workarounds to accommodate different test scenarios, thereby increasing the risk of errors.
Reduced Modularity: Relying on global constants decreases modularity since components become dependent on specific values being set globally. This dependence reduces the reusability of components across different projects or contexts.
Tight Coupling: Global constants integrate specific behaviors and configurations directly into the codebase, making it difficult to adapt or evolve the application without extensive modifications.
Hidden Dependencies: Similar to global variables, global constants obscure the dependencies within an application. It becomes unclear which parts of the system rely on these constants, complicating both the understanding and the maintenance of the code.
Namespace Pollution and Scalability Challenges: Global constants can clutter the namespace and complicate the scaling of applications. They promote a design that isn't modular, hindering efficient distribution across different processes.
Maintenance and Refactoring Difficulties: Over time, the use of global constants can lead to maintenance challenges. Refactoring such a codebase is risky as changes to the constants might inadvertently affect disparate parts of the application.
Module-Level State Duplication: In Python, module-level code might be executed multiple times if imports occur under different paths (e.g., absolute vs. relative). This can lead to duplication of global instances and hard-to-track maintenance bugs, further complicating the application’s stability and predictability.

Injected Parameters

Dynamic Flexibility and Configurability: Dependency injection allows for the dynamic configuration of components, making applications adaptable to varying conditions without needing code changes.
Enhanced Testability: DI improves testability by enabling the injection of mock objects or alternative configurations during tests, effectively isolating components from external dependencies and ensuring more reliable test outcomes.
Increased Modularity and Reusability: Components become more modular and reusable as they are designed to operate with any injected parameters that conform to expected interfaces. This separation of concerns enhances the portability of components across various parts of an application or even different projects.
Loose Coupling: Injected parameters promote loose coupling by decoupling the system’s logic from its configuration. This approach facilitates easier updates and changes to the application.
Explicit Dependency Declaration: With DI, components clearly declare their dependencies, typically through constructor parameters or setters. This clarity makes the system easier to understand, maintain, and extend.
Scalability and Complexity Management: As applications grow, DI helps manage complexity by localizing concerns and separating configuration from usage, aiding in the effective scaling and maintenance of large systems.

Procedural vs OOP

Using Object-Oriented Programming (OOP) and Dependency Injection (DI) can significantly enhance code quality and maintainability compared to a procedural approach with global variables and functions. Here's a simple comparison that demonstrates these advantages:

Procedural Approach: Global Variables and Functions



# Global configuration
database_config = {
    'host': 'localhost',
    'port': 3306,
    'user': 'user',
    'password': 'pass'
}

def connect_to_database():
    print(f"Connecting to database on {database_config['host']}...")
    # Assume connection is made
    return "database_connection"

def fetch_user(database_connection, user_id):
    print(f"Fetching user {user_id} using {database_connection}")
    # Fetch user logic
    return {'id': user_id, 'name': 'John Doe'}

# Usage
db_connection = connect_to_database()
user = fetch_user(db_connection, 1)

Code Duplication: database_config must be passed around or accessed globally in multiple functions.
Testing Difficulty: Mocking the database connection or configuration involves manipulating global state, which is error-prone.
Tight Coupling: Functions directly depend on global state and specific implementations.

OOP + DI Approach



from typing import Dict, Optional
from abc import ABC, abstractmethod

class DatabaseConnection(ABC):
    @abstractmethod
    def connect(self):
        pass

    @abstractmethod
    def fetch_user(self, user_id: int) -> Dict:
        pass

class MySQLConnection(DatabaseConnection):
    def __init__(self, config: Dict[str, str]):
        self.config = config

    def connect(self):
        print(f"Connecting to MySQL database on {self.config['host']}...")
        # Assume connection is made

    def fetch_user(self, user_id: int) -> Dict:
        print(f"Fetching user {user_id} from MySQL")
        return {'id': user_id, 'name': 'John Doe'}

class UserService:
    def __init__(self, db_connection: DatabaseConnection):
        self.db_connection = db_connection

    def get_user(self, user_id: int) -> Dict:
        return self.db_connection.fetch_user(user_id)

# Configuration and DI
config = {
    'host': 'localhost',
    'port': 3306,
    'user': 'user',
    'password': 'pass'
}
db = MySQLConnection(config)
db.connect()
user_service = UserService(db)
user = user_service.get_user(1)

Reduced Code Duplication: The database configuration is encapsulated within the connection object; no need to pass it around.
DI Possibilities: Easily switch out MySQLConnection with another database connection class without changing UserService code.
Encapsulation and Abstraction: Implementation details of how users are fetched or how the database is connected are hidden away.
Ease of Mocking and Testing: UserService can be easily tested by injecting a mock or stub of DatabaseConnection.
Object Lifetime Management: The lifecycle of database connections can be managed more granularly (e.g., using context managers).
Use of OOP Principles: Demonstrates inheritance (abstract base class), polymorphism (implementing abstract methods), and protocols (interfaces defined by DatabaseConnection).

By structuring the application using OOP and DI, the code becomes more modular, easier to test, and flexible to changes, such as swapping out dependencies or changing configurations.

Building the App

You can find all examples and more details with comments at the repo

Starting a new Project

Just a short check-list:

1. Project and Dependency Management with Poetry

Poetry shines not only as a project creation tool but also excels in managing dependencies and virtual environments. Start by setting up your project structure using the following command:



poetry new python-app-architecture-demo

This command crafts a well-organized directory structure: separate folders for Python code and tests, with a root directory for meta-information like pyproject.toml, lock files, and git configurations.

2. Version Control with Git

Initialize Git in your project directory:



git init

Add a .gitignore file to exclude unnecessary files from your repository. Use the standard Python .gitignore provided by GitHub, and append any specific exclusions like .DS_Store for macOS or IDE configs (.idea, .vscode, .zed, etc):



wget -O .gitignore https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore



echo .DS_Store >> .gitignore

3. Manage Dependencies

Install your project’s dependencies using Poetry:



poetry add fastapi pytest aiogram

You can install all dependencies later using:



poetry install

Refer to the official documentation of each library if you need more specific instructions.

4. Configuration Files

Create a config.py file to centralize your application settings—a common and effective approach.

Set environment variables for secrets and parameters:



touch .env example.env

.env contains sensitive data and should be git-ignored, while example.env holds placeholder or default values and is checked into the repository.

5. Application Entry Point

Define the entry point of your application in main.py:

python_app_architecture/main.py:



def run():
    print('Hello, World!')

if __name__ == '__main__': # avoid run on import
    run()

Make your project usable as a library and allow programmatic access by importing the run function in the __init__.py:

python_app_architecture/init.py



from .main import run

Enable direct project execution with Poetry by adding a shortcut in __main__.py. This allows you to use the command poetry run python python_app_architecture instead of the longer poetry run python python_app_architecture/main.py.

python_app_architecture/main.py:



from .main import run
run()

Defining Directories and Layers

Disclaimer:
Of course, every application is different and their architecture will differ depending on the goals and objectives. I'm not saying that this is the only correct option, but I think that this one is fairly average and suitable for a big part of projects. Try to focus on main approaches and ideas rather than specific examples.

Now, let's setup directories for different layers of the application.

Typically, it's wise to version your API (e.g., by creating subdirectories like api/v1), but we'll keep things simple for now and omit this step.



.
├── python_app_architecture_demo
│   ├── coordinator.py
│   ├── entities
│   ├── general
│   ├── mappers
│   ├── providers
│   ├── repository
│   │   └── models
│   └── services
│       ├── api_service
│       │   └── api
│       │       ├── dependencies
│       │       ├── endpoints
│       │       └── schemas
│       └── telegram_service
└── tests

The App
- Entities — App-wide data structures. Purely carriers of data with no embedded logic.
- General — The utility belt! A consolidated hub for shared utilities, helpers, and library facades.
- Mappers — Specialists in data translation, converting between data forms like database models to entities or between different data formats. It's good practice to encapsulate mappers to its usage boundary instead of making them global. For example, models-entities mapper may be part of the repository module. Another example: schemas-entities mapper must stay inside api service and be its private tool.
- Providers — The backbone of core business logic. Providers implement the main logic of the application but remain agnostic of the interface details, ensuring their operations are abstract and isolated.
- Repository — The librarians. Custodians of data access, abstracting the complexities of data source interactions through models, thus isolating database operations from the broader app.
  - Models — Definitions of local data structures interacting with the database, distinct and isolated from Entities.
- Services — Each service acts as a (almost) standalone sub-application, orchestrating its specific domain of business logic while delegating foundational tasks to providers. This configuration ensures centralized and uniform application-wide logic
  - API Service — Manages external communications via HTTP/S, structured around a FastAPI framework.
    - Dependencies — Essential tools and helpers required by various parts of your API, integrated via FastAPI’s DI system.
    - Endpoints — Routes that publicly expose your business logic via HTTP.
    - Schemas — Data structure definitions for API inputs and outputs, confined to their service layer to maintain encapsulation.
  - Telegram Service — Operates similarly to the API Service, providing functionality via Telegram without replicating the core business logic. This is achieved by calling the same providers that API Service uses, ensuring consistency and reducing code redundancy.
Tests — Dedicated solely to testing, this directory contains all test code, maintaining a clear separation from application logic.

The connection between layers will look something like this:

Note that entities are not active components, but only data structures that are passed between layers:

Keep in mind that layers are not directly connected, but only depend on abstractions. Implementations are passed using dependency injection:

This flexible structure allows you to easily add functionality, for example, change the database, create a service, or connect a new interface without extra changes or code duplication, because logic of each module is located on its own layer:

At the same time, all logic of a separate service is encapsulated within it:

Exploring the Code

Endpoint

Let's start from the endpoint:



# api_service/api/endpoints/user.py

from typing import Annotated
from fastapi import APIRouter, Depends, HTTPException, status
from entities.user import UserCreate
from ..dependencies.providers import (
    user_provider, # 1
    UserProvider # 2
)

router = APIRouter()

@router.post("/register")
async def register(
    user: UserCreate, # 3
    provider: Annotated[UserProvider, Depends(user_provider)] # 4
):
    provider.create_user(user) # 5
    return {"message": "User created!"}

Importing dependency injection helper function (we will look at it in a minute)
Importing UserProvider protocol for type annotation
Endpoint requires the request's body to have UserCreate scheme in json format
The provider parameter in the register function is an instance of implementation of UserProvider, injected by FastAPI using the Depends mechanism.
The create_user method of the UserProvider is called with the parsed user data. This demonstrates a clear separation of concerns, where the API layer delegates business logic to the provider layer, adhering to the principle that interface layers should not contain business logic.

UserProvider

Now, let's see the business logic:



# providers/user_provider.py

from typing import Protocol, runtime_checkable, Callable
from typing_extensions import runtime_checkable
from repository import UserRepository
from providers.mail_provider import MailProvider
from entities.user import UserCreate


@runtime_checkable
class UserProvider(Protocol): # 1
    def create_user(self, user: UserCreate): ...

@runtime_checkable
class UserProviderOutput(Protocol): # 2
    def user_provider_created_user(self, provider: UserProvider, user: UserCreate): ...

class UserProviderImpl: # 3

    def __init__(self,
        repository: UserRepository,  # 4 
        mail_provider: MailProvider, # 4
        output: UserProviderOutput | None, # 5
        on_user_created: Callable[[UserCreate], None] | None # 6
    ):
        self.repository = repository
        self.mail_provider = mail_provider
        self.output = output
        self.on_user_created = on_user_created

    # Implementation

    def create_user(self, user: UserCreate): # 7
        self.repository.add_user(user) # 8
        self.mail_provider.send_mail(user.email, f"Welcome, {user.name}!") # 9

        if output := self.output: # unwraping the optional
            output.user_provider_created_user(self, user) # 10

        # 11
        if on_user_created := self.on_user_created:
            on_user_created(user)

Defining the Interface: UserProvider is a protocol that specifies the method create_user, which any class adhering to this protocol must implement. It serves as a formal contract for user creation functionality.
Observer Protocol: UserProviderOutput serves as an observer (or delegate) that is notified when a user is created. This protocol enables loose coupling and enhances the event-driven architecture of the application.
Protocol Implementation: UserProviderImpl implements the user creation logic but does not need to explicitly declare its adherence to UserProvider due to Python's dynamic nature and the use of duck typing.
Core Dependencies: The constructor accepts UserRepository and MailProvider—both defined as protocols—as parameters. By relying solely on these protocols, the UserProviderImpl remains decoupled from specific implementations, illustrating the principles of Dependency Injection where the provider is agnostic of the underlying details, interfacing only through defined contracts.
Optional Output Delegate: The constructor accepts an optional UserProviderOutput instance, which, if provided, will be notified upon the completion of user creation.
Callback Function: As an alternative to the output delegate, a callable on_user_created can be passed to handle additional actions post-user creation, providing flexibility in response to events.
Central Business Logic: The create_user method encapsulates the main business logic for adding a user, demonstrating separation from API handling.
Repository Interaction: Utilizes the UserRepository to abstract the database operations (e.g., adding a user), ensuring the provider does not directly manipulate the database.
Extended Business Logic: Involves sending an email through MailProvider, illustrating that the provider's responsibilities can extend beyond simple CRUD operations.
Event Notification: If an output delegate is provided, it notifies this delegate about the user creation event, leveraging the observer pattern for enhanced interactivity and modular reactions to events.
Callback Execution: Optionally executes a callback function, providing a straightforward method to extend functionality without complex class hierarchies or dependencies.

FastAPI Dependencies

Ok, but how to instantiate the provider and inject it? Let's take a look at the injection code, powered by FastAPI's DI engine:



# services/api_service/api/dependencies/providers.py
from typing import Annotated
from fastapi import Request, Depends
from repository import UserRepository
from providers.user_provider import UserProvider, UserProviderImpl
from providers.mail_provider import MailProvider
from coordinator import Coordinator
from .database import get_session, Session
import config


def _get_coordinator(request: Request) -> Coordinator:
    # private helper function
    # NOTE: You can pass the DIContainer in the same way
    return request.app.state.coordinator

def user_provider(
    session: Annotated[Session, Depends(get_session)], # 1
    coordinator: Annotated[Coordinator, Depends(_get_coordinator)] # 2
) -> UserProvider: # 3
    # UserProvider's lifecycle is bound to short endpoint's lifecycle, so it's safe to use strong references here
    return UserProviderImpl( # 4
        repository=UserRepository(session), # 5
        mail_provider=MailProvider(config.mail_token), # 6
        output=coordinator, # 7
        on_user_created=coordinator.on_user_created # 8
        # on_user_created: lambda: coordinator.on_user_created() # add a lambda if the method's signature is not compatible
    )

Getting a database session through FastAPI's dependency injection system, ensuring that each request has a clean session.
Obtaining an instance of Coordinator from the application state, which is responsible for managing broader application-level tasks and acting as an event manager.
Note: the function returns protocol but not the exact implementation
Constructing an instance of UserProviderImpl by injecting all the necessary dependencies. This demonstrates a practical application of dependency injection to assemble complex objects.
Initializing UserRepository with the session obtained from FastAPI's DI system. This repository handles all data persistence operations, abstracting the database interactions from the provider.
Setting up MailProvider using a configuration token.
Injecting Coordinator as the output protocol. This assumes that Coordinator implements the UserProviderOutput protocol, allowing it to receive notifications when a user is created.
Assigns a method from Coordinator as a callback to be executed upon user creation. This allows for additional operations or notifications to be triggered as a side effect of the user creation process.

This structured approach ensures that the UserProvider is equipped with all necessary tools to perform its tasks effectively, while adhering to the principles of loose coupling and high cohesion.

Coordinator

The Coordinator class acts as the main orchestrator within your application, managing various services, interactions, events, setting the initial state, and injecting dependencies. Here's a detailed breakdown of its roles and functionalities based on the provided code:



# coordinator.py

from threading import Thread
import weakref
import uvicorn
import config
from services.api_service import get_app as get_fastapi_app
from entities.user import UserCreate
from repository.user_repository import UserRepository
from providers.mail_provider import MailProvider
from providers.user_provider import UserProvider, UserProviderImpl
from services.report_service import ReportService
from services.telegram_service import TelegramService


class Coordinator:

    def __init__(self):
        self.users_count = 0 # 1

        self.telegram_service = TelegramService( # 2
            token=config.telegram_token,
            get_user_provider=lambda session: UserProviderImpl(
                repository=UserRepository(session),
                mail_provider=MailProvider(config.mail_token),
                output=self,
                on_user_created=self.on_user_created
            )
        )

        self.report_service = ReportService(
            get_users_count = lambda: self.users_count # 3
        )

    # Coordinator's Interface

    def setup_initial_state(self):
        fastapi_app = get_fastapi_app()

        fastapi_app.state.coordinator = self # 4

        # 5
        fastapi_thread = Thread(target=lambda: uvicorn.run(fastapi_app))
        fastapi_thread.start()

        # 6
        self.report_service.start()
        self.telegram_service.start()

    # UserProviderOutput Protocol Implementation

    def user_provider_created_user(self, provider: UserProvider, user: UserCreate):
        self.on_user_created(user)

    # Event handlers

    def on_user_created(self, user):
        print("User created: ", user)
        self.users_count += 1

        # 7
        if self.users_count >= 10_000:
            self.report_service.interval_seconds *= 10
        elif self.users_count >= 10_000_000:
            self.report_service.stop() # 8

Some state can be shared between different providers, services, layers, and the entire app
Assembling implementations and injecting dependencies
Be aware of circular references, deadlocks, and memory leaks here, see the full code for detatils
Pass the coordinator instance to the FastAPI app state so you can access it in the endpoints via FastAPI's DI system
Start all services in separate threads
Already runs in a separate thread inside the service
Some cross-service logic here, just for example
Example of controlling services from the coordinator

This orchestrator centralizes control and communication between different components, enhancing manageability and scalability of the application. It effectively coordinates actions across services, ensuring that the application responds appropriately to state changes and user interactions. This design pattern is crucial for maintaining a clean separation of concerns and enabling more robust and flexible application behavior.

DI Container

However, in large-scale applications manual DI can lead to a significant amount of boilerplate code. This is when DI Container comes to rescue. DI Containers, or Dependency Injection Containers, are powerful tools used in software development to manage dependencies within an application. They serve as a central location where objects and their dependencies are registered and managed. When an object requires a dependency, the DI Container automatically handles the instantiation and provision of these dependencies, ensuring that objects receive all the necessary components to function effectively. This approach promotes loose coupling, enhances testability, and improves the overall maintainability of the codebase by abstracting the complex logic of dependency management away from the business logic of the application. DI Containers simplify the development process by automating and centralizing the configuration of component dependencies.

For python, there are many libraries providing different DI Container implementations, I looked almost all of them and wrote down the best IMO

python-dependency-injector — automated, class-based, has different lifecycle options like Singleton or Factory
lagom — a dictionary interface with automatic resolve
dishka — good scope control via context manager
that-depends — support for context managers (objects required to be closed in the end), native fastapi integration
punq — more classic approach with register and resolve methods
rodi — classic, simple, automatic

main.py

For the end, let's update the main.py file:



# main.py

from coordinator import Coordinator

def run(): # entry point, no logic here, only run the coordinator

    coordinator = Coordinator()

    coordinator.setup_initial_state()

if name == 'main':

    run()

Conclusion

To gain a comprehensive understanding of the architectural and implementation strategies discussed, it is beneficial to review all files in the repository. Despite the limited amount of code, each file is enriched with insightful comments and additional details that offer a deeper understanding of the application’s structure and functionality. Exploring these aspects will enhance your familiarity with the system, ensuring you are well-equipped to adapt or expand the application effectively.

This approach is universally beneficial across various Python applications. It's effective for stateless backend servers such as those built with FastAPI, but its advantages are particularly pronounced in no-framework apps and applications that manage state. This includes desktop applications (both GUI and command-line), as well as systems that control physical devices like IoT devices, robotics, drones, and other hardware-centric technologies.

Additionally, I highly recommend reading Clean Code by Robert Martin for further enrichment. You can find a summary and key takeaways here. This resource will provide you with foundational principles and practices that are crucial for maintaining high standards in software development.

AI-powered Mobile App with Backend in Two Days + MVVMP Architecture Overview (Tutorial)

Mark Parker — Mon, 27 May 2024 13:46:53 +0000

Creating a Proof of Concept SwiftUI mobile app with clean MVVMP architecture and a small FastAPI backend.

This article delves into the nuts and bolts of creating a Proof of Concept (PoC) of ф mobile app built with the SwiftUI framework and a backend using FastAPI. As an extra, I'll demonstrate effective architecture patterns for SwiftUI apps, specifically MVVMP combined with SOLID principles and Dependency Injection (DI). For android, the code can be easily translated to Kotlin using Jetpack Compose Framework almost without changes.

Why We Need a Backend

Someone might say that you can just cram all the logic into the application, send requests to chatgpt directly and make a backendless app. And I agree, it is indeed possible (and I'll show it later), but the backend provides several important advantages.

The backend serves as the backbone for any sophisticated app, especially those requiring secure data management, business logic processing, and service integration. Here’s why a robust backend is crucial:

Security: A backend helps protect sensitive data and user authentication tokens from MITM (Man-in-the-Middle) attacks. It acts as a secure gateway between the user's device and the database or external services, ensuring that all data exchanges are encrypted and authenticated.
Control Over Service Usage: By managing APIs and user interactions through the backend, you can monitor and control how the app is used. This includes throttling to manage load, preventing abuse, and ensuring that resources are used efficiently.
Database Integration: A backend allows for seamless integration with databases, enabling dynamic data storage, retrieval, and real-time updates. This is essential for apps that require user accounts, store user preferences, or need to retrieve large amounts of data quickly and securely.
Subscription and Freemium Models: Implementing subscription services or a freemium model requires a backend to handle billing, track usage, and manage user tiers. The backend can securely process payments and subscriptions, providing a seamless user experience while ensuring compliance with data protection regulations.
Scalability and Maintenance: With a backend, you can scale your application more effectively. Server-side logic can be updated without needing to push updates to the client, facilitating easier maintenance and quicker rollouts of new features.

In essence, a backend is not just about functionality — it's about creating a secure, scalable, and sustainable environment for your app to thrive.

Explaining the Tech Stack

SwiftUI: The go-to for native iOS apps now that UIKit is on its way out. It's declarative and streamlined, with XCode as the indispensable editor. For android, the code can be easily translated to Kotlin using Jetpack Compose.
FastAPI: Chosen for the backend for its speed, minimal boilerplate, and declarative nature, edited with the superb Zed.dev.
ChatGPT API: Used here as a large language model (LLM); choice may vary based on the need for customization (see Technical Info).
Ngrok: Implements tunneling with a simple CLI command to expose your local server to the internet.

Building the iOS App

Theory: Architecture Patterns

Model View ViewModel Presenter (MVVMP):
- Model: Represents the data structures used in the app, such as Question, Answer, Questionary, and FilledQuestionary. These models are simple and only hold data, following the KISS principle.
- View: SwiftUI views are responsible only for UI presentation and delegate all data and logic to presenters. They contain no business logic and are designed to be simple and focused on UI rendering.
- ViewModel: In SwiftUI, ViewModel is represented by ObservableObject, which serves as a data-only observable model. No methods or logic here.
- Presenter: The Presenter manages all logic related to the module (screen or view), but not the business logic. It communicates with the domain layer for business logic operations, such as interacting with APIs or managing data persistence.
- Domain Layer: This layer encapsulates the business logic of the application and interacts with external resources such as databases, APIs, or other services. It consists of several components, such as Services, Providers, Managers, Repositories, Mappers, Factories, etc.
- Actually, the MP in MVVMP stands for Mark Parker and the full form is "Model View ViewModel by Mark Parker"
SOLID Principles:
- Single-responsibility Principle: Each class should have only one reason to change.
- Open-closed Principle: Components should be open for extension but closed for modification.
- Liskov Substitution Principle: Objects of a superclass should be replaceable with objects of subclasses.
- Interface Segregation Principle: No client should be forced to depend on interfaces it doesn't use.
- Dependency Inversion Principle: Depend on abstractions, not concretes, facilitated by DI.
Dependency Injection (DI): a programming technique in which an object or function receives other objects or functions that it requires, as opposed to creating them internally.

Drafting the Backend

The backend's code is quite simple. Endpoints (main.py):



from typing import Callable
import json
from fastapi import FastAPI, Body, Request, Response
from .models import (Question, FilledQuestionary, DoctorResponseAnswer, DoctorResponseQuestionary)
from .user_card import UserCardSimple
from .prompting import get_response


@app.get("/onboarding", response_model = DoctorResponseQuestionary)
def onboarding():
    return DoctorResponseQuestionary(question=[Question(text=text) for text in UserCardSimple.__fields__.keys()])

@app.post("/doctor")
def doctor(user_card: UserCardSimple, filled_questionary: FilledQuestionary, message: str = Body(...)):
    json_string = get_response(user_card, message, filled_questionary) 
    loaded = json.loads(json_string.strip())
    return loaded

There are two endpoints. The "onboarding" provides a list of anamnesis questions that needs to be filled at the first launch of the app. Answers will be stored on the device and used for personalized future diagnosis. The "doctor" is the main endpoint: it generates questions based on earlier answers and user's card, or returns the result of diagnosis.

Models:



from pydantic import BaseModel


class Question(BaseModel):
    text: str

class FilledQuestionary(BaseModel):
    filled_questions: dict[str, str]

class DoctorResponseAnswer(BaseModel):
    text: str

class DoctorResponseQuestionary(BaseModel):
    questions: list[str]

class UserCardSimple(BaseModel):
    sex: str
    age: int
    weight: int
    height: int
    special_conditions: str

Prompting:



import os
from openai import OpenAI
from .models import FilledQuestionary


api_key = os.environ.get("API_KEY")
client = OpenAI(api_key=api_key)

def get_response(user_card: str, message: str, filled_questionary: FilledQuestionary, max_tokens=200):
    format_question = """{"questions":[{"text":"first question"},{"text":"second question"}]}"""
    format_advice = """{"text":"Advice: Drink more water"}"""

    system_prompt = f"""
    You are a doctor that gives user an opportunity to swiftly check up health and diagnos an illness using anamnes and a short questionary. 
    Your task is to ask short questions and give your opinion and advices.
    Your questions are accamulated in the filled questionary, which is empty in the first itteration. 

    Strive to about 1-2 questions per iteration and up to 6 questions in total (can be less). Questions must be short, clear, shouldn't repeat, 
    and should be relevant to the user's health condition, and should require easy answers.
    Ask questions only in the json format {format_question}.

    Number of answered questions: {len(filled_questionary.filled_questions)}
    If the Number of answered questions is more then 6, you should stop asking questions an`d provide an give your final opinion, 
    an assumption or an advice in the json format {format_advice}.
    """

    prompt = f"""request message: {message}; anamnesis: {user_card}; filled questionary: {filled_questionary};"""

    chat_completion = client.chat.completions.create(
        messages=[
            {
                "role": "system",
                "content": f"{system_prompt}",
            },
            {
                "role": "user",
                "content": f"{prompt}",
            },
        ],
        model="gpt-3.5-turbo",
        max_tokens=max_tokens
    )
    return chat_completion.choices[0].message.content
```

The prompting module utilizes OpenAI's GPT-3.5 to generate responses based on user input, anamnesis, and filled questionnaires. It prompts the user with relevant questions and advice for health diagnosis. As you can see, there is nothing complicated here. The code is elementary, and the prompt is just a set of clear instructions for the LLM. 

Setup the env and run the server using `fastapi dev main.py`.

Details: 
- fastapi.tiangolo.com/tutorial/first-steps
- pypi.org/project/openai/

### Making Localhost Accessible Over the Internet

1. Sign up at ngrok.com and get an access token.
2. Install ngrok from ngrok.com/download.
3. Run `ngrok config add-authtoken <TOKEN>`.
4. Start the service with `ngrok http http://localhost:8080` (adjust the port as necessary).

Find detailed setup instructions at [ngrok documentation](https://ngrok.com/docs/getting-started).

### Coding the App

I won't show the entire source code here, this is what GitHub is for. Find the code at: [HouseMDAI iOS App](https://github.com/HouseMDAI/house-ios/tree/main/HouseMDAI). Instead, I'll focus only on the important (IMO) points.

Let's start with a quick description of the task: we need an app with a textfield on the home screen, ability to ask a set of dynamic questions, and show the answer. Also, we require a one-time onboarding. Okay, let's code.

First thing first, we need some models, and they are pretty simple (KISS principle).
```swift
struct Question {
    var text: String
}

struct Answer {
    var text: String
}

struct Questionary {
    var questions: [Question]
}

struct FilledQuestionary {
    var filledQuestions: [String: String]
}
```

Now, let's do the onboarding. Keep following the KISS and SRP (Single Responsibility Principle), no business logic in views either, only UI. In this case, just the list of questions with scroll. All data and logic is delegated to the presenter. The only interesting thing here is a small helper method `bindingForQuestion`, which probably should be in the presenter but it doesn't matter now.

```swift
import SwiftUI

struct OnboardingView: View {

    @StateObject var presenter: OnboardingPresenter

    var body: some View {
        ScrollView {
            Spacer()
            VStack {
                ForEach(presenter.questions.questions) { question in
                    VStack {
                        Text(question.text)
                        TextField("", text: bindingForQuestion(question))
                            .formItem()
                    }
                    .padding()
                }
            }.padding()

            Button("Save", action: presenter.save)
            Spacer()
        }
    }

    private func bindingForQuestion(_ question: Question) -> Binding<String> {
        Binding(
            get: { presenter.answers.filledQuestions[question.text] ?? "" },
            set: { presenter.answers.filledQuestions[question.text] = $0 }
        )
    }
}
```

You will be surprised, but there is no business logic in the presenter either!

```swift
class OnboardingPresenter: ObservableObject {

    @Published public var answers: FilledQuestionary
    private(set) public var questions: Questionary
    private var completion: (FilledQuestionary) -> Void

    init(questions: Questionary, answers: FilledQuestionary, completion: @escaping (FilledQuestionary) -> Void) {
        self.questions = questions
        self.answers = answers
        self.completion = completion
    }

    func save() {
        completion(answers)
    }
}
```

 Still everything is *simple, stupid*, and have only a *single responsibility*. Presenter must contain only the logic of its view. App-level business-logic is out of its jurisdiction, so the presenter is just delegating it to the top.

Also, you can see that both View and Presenter don't instantiate any of the dependencies but receive them as init parameters. This follows the Dependency Inversion Principle, where high-level modules should not depend on low-level modules, but both should depend on abstractions. This allows for flexibility and easier testing, as well as making it straightforward to replace dependencies or inject mocks for testing purposes.

Using the Dependency Injection Pattern, dependencies are provided from outside the class rather than being instantiated internally. This promotes decoupling and allows for easier maintenance and testing.

Although protocols are not explicitly used in this example, it's worth mentioning that protocols can play a crucial role in code, especially for abstraction and easier testing. By defining protocols for views, presenters, and dependencies, it becomes easier to swap out implementations or provide mocks during testing.

> If you're considering using protocols in SwiftUI Views, there's an important consideration to keep in mind. Since View in SwiftUI is a structure, it requires explicit specification of its property types. This means you'll need to make it a generic structure and pass the type through all the call stack, resulting in a lot of boilerplate code.
> 
> However, there's an alternative approach offered by [MarkParker5/AnyObservableObject](https://github.com/MarkParker5/AnyObservableObject). This library works similarly to native SwiftUI property wrappers but removes the compile-time type check in favor of a runtime one. While this approach may introduce some risks, they are easily mitigated by writing elementary Xcode tests that simply instantiate the views in the same way you do it at runtime.
> 
> By using this alternative, you can simplify your code and streamline the process of working with protocols in SwiftUI Views.

So, if the presenter doesn't contain the business logic, then who does? This is the task for the domain layer, which usually contains Services, Providers, and Managers. They have very similar destiny and the difference between them still is a subject of discussions. Let's create the `OnboardingProvider` that will contain all business-logic of the onboarding process.

```swift
class OnboardingProvider: ObservableObject {

    init() {
        loadFilledOnboardingFromDefaults()
    }

    // MARK: Interface

    @Published private(set) var needsOnboarding: Bool = true

    private(set) var filledOnboarding: FilledQuestionary? {
        didSet {
            if let filledOnboarding {
                saveFilledOnboardingToDefaults(filledQuestionary: filledOnboarding)
            }
        }
    }

    func getOnboardingQuestionary() -> Questionary {
        // NOTE: it's better to take the questions from the backend
        Questionary(questions: [
            Question(text: "sex"),
            Question(text: "age"),
            Question(text: "weight"),
            Question(text: "height"),
            Question(text: "special_conditions"),
        ])
    }

    func saveOnboardingAnswers(filledQuestionary: FilledQuestionary) {
        needsOnboarding = false
        filledOnboarding = filledQuestionary
    }

    // MARK: - Private

    private func saveFilledOnboardingToDefaults(filledQuestionary: FilledQuestionary) {
        UserDefaults.standard.removeObject(forKey: "filledOnboarding")
        let encoder = JSONEncoder()
        let encoded = try! encoder.encode(filledQuestionary)
        UserDefaults.standard.set(encoded, forKey: "filledOnboarding")
    }

    private func loadFilledOnboardingFromDefaults() {
        guard let object = UserDefaults.standard.object(forKey: "filledOnboarding") else {
            needsOnboarding = true
            return
        }
        let savedFilledQuestionary = object as! Data
        let decoder = JSONDecoder()
        let loadedQuestionary = try! decoder.decode(FilledQuestionary.self, from: savedFilledQuestionary)
        self.filledOnboarding = loadedQuestionary
        self.needsOnboarding = false
    }
}
```

Again, it handles only one responsibility: managing the business logic of the onboarding process. This *encapsulation* allows other classes to interact with it without needing to worry about its internal implementation details, promoting a cleaner and more maintainable codebase.

Now, let's put everything together in the entry point.
```swift
import SwiftUI

@main
struct HouseMDAI: App {

    @StateObject private var onboardingProvider: OnboardingProvider
    @StateObject private var onboardingPresenter: OnboardingPresenter
    @StateObject private var homePresenter: HomePresenter

    init() {
        let onboardingProvider = OnboardingProvider()

        let onboardingPresenter = OnboardingPresenter(
            questions: onboardingProvider.getOnboardingQuestionary(),
            answers: FilledQuestionary(filledQuestions: [:]),
            completion: onboardingProvider.saveOnboardingAnswers
        )

        let homePresenter = HomePresenter()

        _onboardingProvider = StateObject(wrappedValue: onboardingProvider)
        _onboardingPresenter = StateObject(wrappedValue: onboardingPresenter)
        _homePresenter = StateObject(wrappedValue: homePresenter)
    }

    var body: some Scene {
        WindowGroup {
            if onboardingProvider.needsOnboarding {
                OnboardingView(presenter: onboardingPresenter)
            } else {
                TabView {
                    HomeView(presenter: homePresenter)

                    if let profile = onboardingProvider.filledOnboarding {
                        ProfileView(profile: profile)
                    }
                }
            }
        }
    } // body
}
```

This SwiftUI app sets up its initial state using `StateObject` property wrappers. It initializes an `OnboardingProvider`, `OnboardingPresenter`, and `HomePresenter` in its init method. The `OnboardingProvider` is responsible for managing onboarding-related data, while the `OnboardingPresenter` handles the logic for the onboarding view. The `HomePresenter` manages the main home view.

The body of the app's scene checks if onboarding is needed. If so, it presents the `OnboardingView` with the `OnboardingPresenter`. Otherwise, it presents a `TabView` containing the `HomeView` with the `HomePresenter` and, if available, the `ProfileView`.

Now it's time for the home view. The logic is simple:
1. Get a message from user
2. Using the message, request a list of questions from the backend 
3. Show the questions one by one using the native push navigation
4. Add answers to the request and repeat 2-4 until the backend-doctor returns a final result
5. Show the final result

```swift
struct HomeView: View {

    @StateObject var presenter: HomePresenter

    var body: some View {
        NavigationStack(path: $presenter.navigationPath) {
            VStack {
                // 1
                Text("How are you?")
                TextField("...", text: $presenter.message)
                    .lineLimit(5...10)
                    .formItem()

                // 2
                Button("Send", action: presenter.onSend)
            }
            .padding()
            .navigationDestination(for: NavigationPage.self) { page in
                switch page {
                case .questinary(let questions, let answers):
                    // 3
                    QuestionaryView(
                        presenter: QuestionaryPresenter(
                            questions: questions,
                            answers: answers,
                            completion: presenter.onQuestionaryFilled
                        )
                    )
                case .answer(let string):
                    // 5
                    VStack {
                        Text("The doctor says...")
                        Text(string)
                            .font(.title2)
                            .padding()
                    }
                }
            }
        }
    }
}
```

Looks like I've missed the 4th point... or not? Since the view can't content any logic, this part in handled by its presenter.

```swift
enum NavigationPage: Hashable {
    case questinary(Questionary, FilledQuestionary)
    case answer(String)
}

class HomePresenter: ObservableObject {

    @Published var message: String = ""
    @Published var navigationPath: [NavigationPage] = []

    init(message: String = "") {
        self.message = message
    }

    func onSend() {
        Task {
            let doctor = DoctorProvider()
            let answer = try! await doctor.sendMessage(message: message)

            switch answer {
            case .questions(let questions):
                navigationPath.append(.questinary(questions, FilledQuestionary(filledQuestions: [:])))
            case .answer(let string):
                navigationPath.append(.answer(string))
            }
        }
    }

    func onQuestionaryFilled(filled: FilledQuestionary) {
        Task {
            let doctor = DoctorProvider()
            let answer = try! await doctor.sendAnswers(message: message, answers: filled)

            switch answer {
            case .questions(let newQuestions):
                navigationPath.append(.questinary(newQuestions, filled))
            case .answer(let string):
                navigationPath.append(.answer(string))
            }
        }
    }
}
```

It manages the user's message input and updates the navigation path based on responses from the backend.

Upon sending a message, the `onSend()` method sends the message to the backend using the `DoctorProvider` and awaits a response. Depending on the response type, it updates the navigation path to either display a set of questions or show a final answer.

Similarly, when a questionary is filled, the `onQuestionaryFilled()` method sends the filled questionary to the backend and updates the navigation path accordingly.

There's a slight code duplication here between the `onSend()` and `onQuestionaryFilled()` methods, which could be refactored into a single method to handle both cases. However, this is left as an exercise for further refinement.

The Questionary module (View+Presenter) is almost a copy of the Onboarding and simply delegates the logic up to `HomePresenter`, so I don't see a need to show the code. Again, there is github for that.

The last things I want to show are two implementations of `DoctorProvider` which the only responsibility is to call the API and return `DoctorResponse`. The first one uses our backend.

```swift
import Alamofire

enum DoctorResponse {
    case questions(Questionary)
    case answer(String)

    init(from string: String) throws {
        if let data = string.data(using: .utf8) {
            if string.contains("\"questions\""){
                let decoded = try! JSONDecoder().decode(Questionary.self, from: data)
                self = .questions(decoded)
            } else if string.contains("\"text\"") {
                let decoded = try! JSONDecoder().decode(Answer.self, from: data)
                self = .answer(decoded.text)
            } else {
                throw NSError(domain: "DoctorResponseError", code: 0, userInfo: [NSLocalizedDescriptionKey: "Unknown response format"])
            }
        } else {
            throw NSError(domain: "DoctorResponseError", code: 1, userInfo: [NSLocalizedDescriptionKey: "Invalid string encoding"])
        }
    }
}

class DoctorProvider {

    private let baseUrl = ""

    func sendMessage(message: String) async throws -> DoctorResponse {
        try! await sendAnswers(message: message, answers: FilledQuestionary(filledQuestions: [:]))
    }

    func sendAnswers(message: String, answers: FilledQuestionary) async throws -> DoctorResponse {

        struct DoctorParams: Codable {
            var message: String
            var userCard: [String: String]
            var filledQuestionary: FilledQuestionary
        }

        let onboard = OnboardingProvider()

        let paramsObject = DoctorParams(
            message: message,
            userCard: onboard.filledOnboarding!.filledQuestions,
            filledQuestionary: answers
        )

        let encoder = JSONParameterEncoder.default
        encoder.encoder.keyEncodingStrategy = .convertToSnakeCase

        let responseString = try await AF.request(
            baseUrl + "/doctor", 
            method: .post,
            parameters: paramsObject,
            encoder: encoder
        ).serializingString().value

        return try! DoctorResponse(from: responseString)
    }
}
```

The second one calls openai api directly (backendless approach) and is almost a copy of the prompting module from the backend.

```swift

class PromptsProvider {

    private(set) public var homeRole = "" // TODO: take from the backend

    func message(message: String) -> String {
        return message
    }

    func profile(profile: FilledQuestionary) -> String {
        return try! jsonify(object: profile)
    }

    func answers(filled: FilledQuestionary) -> String {
        return try! jsonify(object: filled)
    }

    // MARK: - Private

    private func jsonify(object: Encodable) throws -> String {
        let coder = JSONEncoder()
        return String(data: try coder.encode(object), encoding: .utf8) ?? ""
    }
}

class HouseMDAIProvider {

    private var openAI: OpenAI

    init() {
        openAI = OpenAI(apiToken: "")
    }

    func sendMessage(message: String) async throws -> DoctorResponse {
        try! await sendAnswers(message: message, answers: FilledQuestionary(filledQuestions: [:]))
    }

    func sendAnswers(message: String, answers: FilledQuestionary) async throws -> DoctorResponse {
        // NOTE: Draft version, DI should be used instead!
        let promptProvider = PromptsProvider()
        let profile = OnboardingProvider().filledOnboarding!

        let query = ChatQuery(model: .gpt3_5Turbo, messages: [
            Chat(role: .system, content: promptProvider.homeRole),
            Chat(role: .user, content: promptProvider.profile(profile: profile)),
            Chat(role: .user, content: promptProvider.message(message: message)),
            Chat(role: .user, content: promptProvider.answers(filled: answers)),
        ])

        let result = try await openAI.chats(query: query)
        return try! DoctorResponse(from: result.choices[0].message.content ?? "")
    }
}
```

Both classes expose the same interface, so they can (should) implement the same protocol and be easily interchangeable thanks to protocol and DI. We didn't get around to this during development, so let this also remain homework.
### Another Example

Explore a more refined example of this architecture in my project TwiTreads at [github.com/MarkParker5/TwiTreads](https://github.com/MarkParker5/TwiTreads)

### What to Do Next

- Integrate authentication and user database into the backend. Utilize the official FastAPI's template from [FastAPI Project Generation](https://fastapi.tiangolo.com/project-generation).
- Implement authentication flow in the app.
- Focus on enhancing the app's design to improve user experience. Let's make beautiful apps!

## Conclusion

The projects and code links included serve as real-world examples to jumpstart your own development. Remember, the beauty of technology lies in iteration. Start simple, build a prototype, and continuously refine it. Each step forward brings you closer to mastering the art of software development and potentially the next big breakthrough in tech.  Happy coding!

Dr. House — AI Diagnostician in your phone. Passing the Startup Torch to Capable Hands

Mark Parker — Wed, 22 May 2024 11:36:13 +0000

Introducing our healthcare app and passing the startup torch to capable hands. Now open source.

This article picks up where the previous one left off, How We Built an AI Startup in a Weekend Hackathon in Germany, focusing more on the final product rather than the hackathon process itself.

When you're creating an AI product about health, there is always a question of ethics, accuracy, responsibility, and trust. That's why it's important to separate healthy lifestyle products and real medical ones. We thought long and hard about the line between them and how close we can get to it. It's a complex question, but we found a solution: create two standalone products that are far away from the line but on opposite sides.

"Best Friend"

The first one is about a healthy lifestyle. It's your virtual best friend, and even more: assistant, coach, motivator, sometimes even your mom or a mini psychologist. By collecting essential information about you from the chat and by having in memory your anamnesis, bio, and history, the best friend can just listen to how you spend your day, comment on it, help you with everyday advice and suggestions, or even help you move towards your goals and dreams using personalized motivation, human sympathy, and understanding your feelings.

"Dr. House"

Problem

The second product is a real medical one. Let's begin with the problem:

The complexity of the diagnostic process itself due to the complex structure of the human body and the huge number of possible cases that cannot always be completely treated by a doctor
Overburdened healthcare systems and professionals
Inefficient and delayed diagnosis in healthcare, leading to worsened patient outcomes.
Accessibility issues for remote or underserved populations
People's reluctance to visit hospitals, fear of doctors.

Diagnosis is important

Why is diagnosis so critical? Einstein is quoted as having said, “If I had an hour to solve a problem, I'd spend 55 minutes thinking about the problem and five minutes thinking about solutions.” The point he makes is significant: preparation has great value to problem-solving. The same holds true in medicine. Professionals say: correct diagnosis is ~70% of healing. And we believe we can improve 70% of modern medicine via a single AI product.

Implementation

Meet Dr. House — AI diagnostician in your phone. A mobile app that provides AI-powered diagnosis in minutes.

Now, how are we going to achieve this? From the beginning of time until now, we believe that the best way of communication is speech. If you want to know something — ask questions. And by asking questions, I mean asking correct questions. So, we're going to make an app that will have your full anamnesis and will ask correct personalized questions and based on the answers suppose possible diagnoses. Sounds pretty simple but helpful, isn't it? And much better than googling some of your symptoms (I have cancer every time).

And it helps not only ordinary people. Doctors can also use this for double-checks, second opinions, or preliminary prognoses, for example in an ambulance.

Also, when Dr. House recommends a visit to the hospital, the process will be significantly faster because the app already has complete anamnesis, medical history, and a filled questionnaire, so both the customer and doctor need to spend significantly less time. And the same app can be used as an emergency card if the user is “offline”.

Can do better?

Can it be even better? We say yes! How? Integration! The app can also take into account info from Apple's HealthKit and medical devices. Or vice versa, the API can transfer data to the hospital (and vice versa) even without direct human contact.

If the app monitors one's health, it means the person can be sent home from the hospital much earlier and free up space for somebody who requires it more. Doctors will monitor the status remotely, and the app will notify them if something is wrong.

Also, if we want ordinary people to use this app, we should add a better description of diseases using simple words; translate from medical to English.

Conclusion

Unfortunately, our team does not have the opportunity to work on this startup full-time, so we published all the results of our work in the public domain. You can find the slides for this article here . For full details on the project, including the source code and the custdev, check the GitHub repository.

How We Built an AI Startup in a Weekend Hackathon in Germany

Mark Parker — Tue, 21 May 2024 15:49:20 +0000

In this article, I share 8 basic steps to create a startup using our project as an example. All sources are open.

Here's a rundown of my weekend at a Cologne hackathon, where we aimed to start an AI startup in just two days. We went from pitching ideas on Friday night to demoing a working app by Sunday. It involved coding late into the night, figuring out last-minute tech snags, and even putting together a presentation minutes before our demo. As a bonus, I have highlighted a to-do list of the main points for creating a startup.

A few weeks ago, I found myself in Cologne for an electrifying AI Startup Hackathon hosted by Startplatz, situated in the heart of MediaPark. The venue buzzed with ideas on the third floor of a vibrant office building, setting the stage for a weekend of innovative frenzy.

Day 1: Ideation and Team Formation (Friday, 6pm to 10pm)

The event kicked off with around 40 participants, each pitching their ideas anonymously. After a democratic voting process, the top eight concepts were selected for development. These ideas ranged from an AI for paramedics (our baby, dubbed "AI Dr. House") to something as quirky as AI evaluating scores in Warhammer — quite the spectrum!

Step 1. Start with an Idea
Pinpoint a unique concept that addresses an unsolved problem or improves on existing solutions.

Here's a snapshot of the diversity and creativity showcased in the pitches:

Paramedic AI (ours): Enhancing emergency medical responses with AI.
LLM without Hallucination: Aiming to create a more reliable language model.
Knowledge Management Through & With AI: Harnessing AI to optimize information flow.
Gesture Recognition for Contactless Playback Control: Innovating user interfaces with computer vision.
SchoolGPT: Applying groundbreaking technology in educational settings.
Evaluate Scores in Warhammer with AI: Bringing AI to the fantasy battlefield.
And a couple more, each brimming with potential.

Step 2. Determine the Pain You Solve
Identify the specific challenges your potential customers face and how your product can address these issues effectively.

Each team then refined their ideas, weighing pros and cons, potential impacts, and business models. The day wrapped up with networking over pizza, setting a casual yet ambitious tone for the weekend.

Night 1: Exploring Cologne

While others retreated for the night, I embraced the Cologne nightlife, from bustling business districts to tranquil residential areas. My detour included culinary stops and riverside reflections. However, the relentless drive of a startup founder never truly powers down; I coded an early draft of our diagnostician app in Xcode. Later, duty called from my primary venture, MajorDom, requiring a few dedicated hours in Jira to keep our other projects on track until dawn.

Day 2: Intensive Development and Unexpected Pivots (Saturday, 8am-10pm)

Grateful for the coworking space's hospitality, I managed to sneak in a breakfast and an hour of 'meditative' closed-eye thinking before diving into the fray at 9:15am.

Energized, we started with a lively warm-up session followed by an insightful lecture on customer development and product positioning. We immediately put this newfound knowledge to the test by drafting a questionnaire to better gauge public opinion and refine our project's direction.

CustDev: Define the Target Audience Understand who your customers are, what their needs are, and how they behave. Engage with them early through customer development interviews to refine your product's focus.

It's also important to ask questions about the past and present, such as "How often do you visit the doctor?", but not questions about the future, such as "Would you use an app instead?". The first questions give a real picture, while the second are unreliable hallucinations. Also, don’t start an interview like “We’re developing an app to replace a doctor”, because then the conversation will become emotional and people will tailor the answers you want to hear instead of telling the truth, which you might not like. Instead, ask questions that are as neutral as possible.

Some of our custdev interviews can be found here.

Also, interviews with potential customers may give you the first FAQ list, which helps to improve the pitch. Our FAQ can be found here.

Analyze Alternatives and Your Competitors Conduct thorough research on both direct competitors and adjacent market players. Understand their strengths, weaknesses, and how they meet customer needs.

Although we did not find any direct competitors, we still noted down other projects in this area that might be useful to us. The list is here.

Develop a UVP and a Pitch Craft a Unique Value Proposition that clearly articulates why your product is different and better than others. Perfect a compelling pitch for different stakeholders (investors, customers, partners).

Since we found no direct competitors, creating a unique offer was not difficult, so we simply described our updated vision.

Figure Out the Monetization Model and Business Model Determine how your business will make money — through subscriptions, ads, direct sales, etc. Decide whether you'll operate on a B2B (business-to-business), B2C (business-to-consumer), or another framework like SaaS (Software as a Service). Consider the scalability and potential for recurring revenue.

Our project turned out to be quite flexible in terms of monetization, so we can experiment with different options: from SaaS to B2B partnership with hospitals. The list can be found here.

Mid-morning brought a welcome surprise — two engineers from Microsoft dropped by to impart wisdom on data science, GPT models, and the broader AI landscape, sprinkling in valuable tips and tricks. Admittedly, I may have nodded off during the 20-minute segment on prompt engineering, but I assure you, the rest was captivating.

Create a PoC to Test the Idea Develop a Proof of Concept to demonstrate the feasibility of your idea in solving the problem at hand. Use this to gather feedback and make necessary adjustments.

The bulk of the day was spent on development. While rival teams wrestled with GPTs and their APIs, our squad tackled ethical dilemmas, the nuances of European regulations, and the intricacies of prompt design, leading us to pivot from a strictly medical-focused app to a broader lifestyle application. Meantime, I was fighting the urge to fall asleep under the table, but continued writing code.

By late afternoon, our proof of concept was nearly operational: a sleek SwiftUI app interface with a FastAPI backend utilizing the (not so) quick ChatGPT API. A pesky 422 validation error, caused by a slight mismatch in data models between the frontend and backend, was all that stood in our way. We opted to tackle this glitch after a good night's rest.

We wrapped the day with more pizza and networking. Fortunately, this time I managed to secure a hotel room just a five-minute walk from the hackathon venue — finally, some well-deserved sleep was within reach.

Day 3: Final Developments and Dual Demos (Sunday, 9am-2pm)

The last day of development often involves refining and scaling ideas, but this time, the challenge was tougher. We were straddling the line between medical and lifestyle categories, and every tweak nudged us towards one side. I believe in creating products without limits or compromises — my philosophy is simple: if you don’t like it, don’t use it.

A good night's sleep brought clarity and a bold new vision. First thing in the morning, I shared this breakthrough with the team, using a flip chart to map out our strategy. We decided to split our efforts into two distinct apps: one strictly medical, staying true to our original concept, and another purely for lifestyle purposes.

We divided into two subteams of two each to tackle the projects. The medical app and its backend were quickly brought up to speed and stabilized. Thanks to Ngrok, we had a public URL for our backend, bringing "Dr. House" to life just in time for the demo. Meanwhile, the lifestyle-focused team used a more straightforward approach with the partyrock constructor from aws to finalize the "Best Friend AI" app (the demo is here).

With only 20 minutes to the curtain call, we realized we hadn't prepared a formal presentation — ironically, that had been our morning's mission! With the clock ticking, we rapidly assembled a coherent plan and cobbled together several impactful keynote slides.

The challenge intensified as each team was allocated just five minutes for their pitch and an additional five for questions — hardly enough to cover one product, let alone two. The clock wound down right before the demo, but we were lucky (or we planned it, nobody knows): the first question from the audience was to show the demo. This "accidental" timing allowed us to sneak in some extra minutes under the guise of answering queries. We used airplay to broadcast a live screencast from an iphone to the stage screen via my macbook, turning our presentation into an engaging showcase that resonated well with the audience. It was not only a demonstration of our apps' capabilities but also a testament to quick thinking and adaptability under pressure.

What's next?

Develop and Launch the MVP Using the Pareto (80-20) Principle Focus on the 20% of features that deliver 80% of the value. Quickly develop and launch a Minimum Viable Product to start the learning cycle, aiming to provide maximum value while spending minimum time and resources.

Remember, the beauty of technology lies in iteration. Start simple, build a prototype, and continuously refine it. Each step forward brings you closer to mastering the art of software development and potentially the next big breakthrough in tech.

Unfortunately, our team does not have the opportunity to work on this startup full-time, so we published all the results of our work in the public domain. You can find the slides here and the text of my speech here (written from memory a week later). For full details on the project, including all notes and the source code, check the GitHub.

To sum up, the hackathon was fantastic. I made new friends, expanded my network, and gained valuable knowledge, experiences, and team work skills. It was a great mix of geeks, nerds, developers, data scientists, and entrepreneurs. Potentially, each such hackathon can generate strong teams with interesting startups in a weekend. I highly recommend these events and look forward to the next one.

S.T.A.R.K - The First Voice Assistant's Framework

Mark Parker — Wed, 20 Sep 2023 09:08:22 +0000

Hello, tech enthusiasts! Today, I'm thrilled to introduce you to S.T.A.R.K, the Speech and Text Algorithmic Recognition Kit. If you've ever dreamt of creating a voice assistant that's modern, advanced, and incredibly intuitive, S.T.A.R.K is your answer.

Why S.T.A.R.K?

Autonomous and Privacy-Centric: In an age where data privacy is paramount, S.T.A.R.K operates entirely on-device. This ensures that your data remains private, giving you peace of mind.
Context-Awareness: With S.T.A.R.K, you can easily define context and parameters for subsequent requests. It even allows you to parse multiple commands simultaneously, offering a seamless user experience.
Asynchronous Commands: Start a task and continue using your voice assistant. S.T.A.R.K will notify you upon completion, ensuring you're always in the loop.
Multiple Responses: Get real-time updates for ongoing tasks. Whether it's monitoring download progress or tracking a delivery, S.T.A.R.K keeps you informed.
Advanced Patterns Parsing: Custom patterns syntax simplifies the process of extracting any parameter from strings, making it effortless to understand and respond to user commands.
Extendable with Leading Language Models: Enhance S.T.A.R.K's cognition by integrating it with top-tier language models like ChatGPT.
Multilingual Support: Interact with your voice assistant in multiple languages, making it globally accessible.
Absolute Customization: Craft intricate commands, integrate various speech or text interfaces, and even override existing classes to make your voice assistant truly unique.
Community Support: Join the STARK-PLACE repository and tap into a library filled with community extensions. Use commands crafted by others and share your innovations.

Get Involved

For a deeper dive into each feature and to understand the full capabilities of S.T.A.R.K, check out the official documentation.

If you're as excited about S.T.A.R.K as we are, head over to the GitHub repository. If you find it valuable, don't forget to add a star ⭐ to the repo. This way, you won't miss out on any updates, and it helps others discover this fantastic framework!

Dive in, explore, and let your voice be heard!

Inside MajorDom v1.0: Exploring the Architecture of a New Smart Home System

Mark Parker — Thu, 01 Jun 2023 15:11:37 +0000

Original article

In the previous article, I talked about the origin of the idea to create a new smart home. Now, I want to take a closer look at the architecture of the system.
MajorDom consists of several key components: devices, hub, cloud, bridge, mobile application, and voice assistant.
Devices play a crucial role in the system as they enable control over physical parts of the home. They communicate using radio modules and the "Merlin" protocol that receive commands from the hub, and transmit events back to it.
The hub is the central element of the system. It manages the devices and coordinates their operations. The hub holds the main database with information about users, home, rooms, and devices. Through a local HTTP server and WS server, the hub provides an API for interacting with the database and high-level controlling the devices.
The cloud is the server-side component and plays a vital role in user authentication. It stores the database of users, homes, hubs, and their access rights. Device models with a list of parameters and a firmware update system are also stored in the cloud.
The bridge is a WS server that provides communication between the hub and remote user over the internet. It enables sending commands and receiving information from the hub without being within the home's local network.
The system can have multiple bridges located in different places. Clients select the nearest or least loaded bridge to minimize communication delays.
One of the main features of the MajorDom is its fault tolerance. Despite the collapse of one or multiple bridges, the system perseveres and maintains its functionality. The remaining available bridges take on the tasks of the inactive bridges, ensuring uninterrupted data exchange between the hub and clients.
Even a complete loss of internet connection on the hub is not a problem. All the logic and command processing occur locally, ensuring independence from the internet connection and maintaining the ability to control devices within the local network. However, such scenarios are rare since the hub can be simultaneously connected via Wi-Fi and an Ethernet cable, and future support for cellular network will be added.
Smart home control is achieved through a mobile application that provides a user-friendly interface. However, in practice, the role of the mobile application often reduces to system configuration, while day-to-day device management is carried out using automatic scenarios and the voice assistant.
Like the hub, the voice assistant can work completely offline, ensuring security, privacy, and reliability of use.
Most importantly, now anyone, even those without programming experience, can install the MajorDom system. In the next article, I will share a detailed guide on how to do it.

Building a Smart Home - from Voice Assistant to MajorDom v1.0

Mark Parker — Fri, 26 May 2023 06:46:01 +0000

Original post

In 2019, I first learned about the possibility of speech recognition and synthesis in Python. Google Assistant, Siri, Cortana, and other assistants were even more limited and helpless than they are now. Adding custom voice commands was out of the question. That's when I became inspired to create my own voice assistant that would rival even Tony Stark's Jarvis.

While working on the core functionality, I started thinking about where to host this assistant. Keeping a laptop constantly powered on was not an option, and I didn't have any other computers available. That's when I discovered the Raspberry Pi single-board computers. I wanted my voice assistant to be able to control lights, LED strips, and curtains. Arduino boards were great for handling such tasks. The only thing left was to find a way to send commands to the Raspberry Pi. I didn't want to use Wi-Fi or Bluetooth right from the start. I found information online about the nRF24L01 modules, gave them a try, and liked the results.

This system worked quite well, but it had two key drawbacks:

The range was limited by the sensitivity of the microphone.
With a good microphone, everything worked perfectly within a room, but not beyond.

For each parameter of each device, I had to add identical voice commands that only differed in the address and message. It was inconvenient, but tolerable for the time being.
To solve the first issue, I added http interface to the voice assistant using Django, which could accept an audio file or a string. In combination with a Kotlin mobile application, I created a wireless microphone, expanding the range to the router's coverage area, meaning from the room to the entire apartment and even slightly beyond. Carrying a phone around the home wasn't always convenient, so a few days later, I developed an application for my Wear OS smartwatch, which turned out to be an incredibly handy solution.

However, I desired more – access to my assistant anytime, not just at home. The simplest solution was a using a Telegram bot as the input-output interface. However, I couldn't shake the feeling that a bot wasn't quite right. I decided to keep it as a temporary solution until I had time to develop something better.

I wanted to be able to use my mobile application to access the assistant remotely. I just needed to find a way to send a request to the local Django server without being on the local network. I was ready to open and forward ports on my router, but my provider didn't give me a public IP address. That's when I tried ngrok. It worked well at first, but in the free version, the server occasionally crashed and changed its address. I quickly dismissed the VPN tunnel option. The cost of a VPS was equivalent to the ngrok subscription, but the implementation was much more complex.

Then I remembered that I had free hosting for PHP websites on Beget and reinvented Long Polling and queues. The implementation was straightforward: the application sent a request to the hosting server, where the PHP code added the request body (JSON) to the end of an array and wrote it to a local file. The Raspberry Pi at home sent a read request to this file every second, and after reading it, cleared the array. This way, I was able to send commands home from anywhere on the planet! Similarly, I set up receiving responses from the assistant: I duplicated the implementation and reversed the roles. Two files and four endpoints on the free PHP hosting provided me with stable bidirectional communication with my home assistant. Shortly after, I taught the assistant to send me messages on its own, such as the room number of the next class at the beginning of each break. Before I could boast about it in college, someone started spamming me at home. I had to add authentication: the login and password were hardcoded in the application, and the server had a check kind of this:



if ($login == 'markparker' && $password == 'MyVeryStrongP@ssw0rd!') {};

The application's repositories were private, and the server had no repository (why have a repository for just one file with less than 100 lines?), so the level of security was more than sufficient.

Shortly after, the system gained its first automatic command trigger. With the help of a small feature in my application, I was able to capture an event every time an alarm went off on my phone. This trigger launched the first full scenario: the curtains opened simultaneously, the assistant announced the time, weather, and class schedule at the college. If the room was still dark, the lamp smoothly turned on. At that moment, I felt like a real Tony Stark.

Then I wanted to add more automatic scenarios using motion sensors, presence detectors, lighting sensors, and so on. At this point, the second drawback I mentioned earlier became more noticeable. There was a lot of code duplication, and working with it became less convenient. The project only had the concept of voice commands; there was no notion of devices and triggers. That's when I realized how much my voice assistant had grown: I was already building a full-fledged smart home, not just a question-and-answer assistant.

This realization led me to the decision to separate the voice assistant and make the smart home a standalone project, focusing on device control rather than voice commands. And I decided to do it properly from the start, with a full-fledged server, databases, authentication, and a mobile application. Later, a college professor suggested to use web sockets instead of my php array-to-file workaround. This is how I implement remote control of devices over the Internet.

The overall concept remained unchanged: a hub in the form of a Raspberry Pi single-board computer controls Arduinos via the nRF24L01 radio module. I'll explain the architecture in more detail in the next article.

How to Localize All Your iOS Apps into 20 Languages in 5 Minutes

Mark Parker — Sat, 04 Mar 2023 19:47:31 +0000

Original post: https://markparker.me/blog/localize-ios-app-in-5-minutes

Introduction

In today's globalized world, the demand for mobile applications that cater to users from different countries and regions has increased significantly. To reach a wider audience, it's important for iOS application developers to make their apps accessible to users in multiple languages. Localizing an iOS app can offer many benefits:

Reach a wider audience: By localizing your app, you can reach users who may not speak your app's default language. This can help you tap into new markets and increase your user base.
Improve user experience: Users are more likely to use and enjoy an app that is available in their native language. Localizing your app can help you provide a better user experience, which can lead to better reviews, ratings, and retention rates. Localizing your app can give you a competitive advantage in regions where your competitors may not have localized their apps.
Increase revenue: Localizing your app can lead to increased revenue, as users are more likely to make in-app purchases or pay for subscriptions if the app is available in their native language.

But there are also a few problems and potential issues that developers may run into. Localizing an app can be time-consuming and resource intensive, especially for apps with a large amount of content and a long list of languages. Developers must allocate sufficient time and resources to ensure effective localization.

But we wouldn't be developers if we didn't always try to automate everything. Automated localization can translate content quickly and efficiently, reduce the costs associated with manual translation, such as hiring professional translators or dedicating internal resources to the task. This is especially effective if the application is being created by a single developer.

Prepare your project

I won't go into detail about how localization of strings works in a xcode project, there are already many other tutorials on this subject. I'll just highlight a few key steps:

Create Localizable.strings file and fill it with strings you want to localize.



/* optional description */
"[key]" = "[string]";

/* Example: */
"welcome text" = "Welcome to XCodelocalize";

2.  Go to the project file settings, add the desired languages. Apple recommended EFIGS (English French Italian German Spanish) + Chinese as a base.
3.  Create Localizable.strings files for all selected languages. You may also want to localize plist, storyboard and intentdefinition files.

## Install [XCodeLocalize](https://github.com/MarkParker5/XCodeLocalize)

Unexpectedly, the ios development tool turned out to be written in python, so make sure you have python 3.9+

After that, install the tool using [pip](https://pypi.org/project/xcodelocalize/):

pip3 install xcodelocalize


Also, available installations from .whl file from [github releases](https://github.com/MarkParker5/XCodeLocalize/releases/latest) or via poetry from [source code](https://github.com/MarkParker5/XCodeLocalize).

## Run automatic localization

`cd` to the project root folder and run

xcodelocalize [OPTIONS]

or

python3 -m xcodelocalize [OPTIONS]


### Options

-  `--base-language`: code of the language from which all strings will be translated. _[default: 'en']_
-  `--override / --no-override`: a boolean value that indicates whether strings that already exist in the file will be translated. Retranslate if `override`, skip if `no-override`. _[default: no-override]_
-  `--format-base / --no-format-base`: sort base file strings by key. _[default: no-format-base]_
-  `--file`: Names of the strings files to be translated. Multiple files can be specified. If not specified, all files will be translated. _[default: None]_
    Example:
    ```


    xcodelocalize --file InfoPlist
    xcodelocalize --file InfoPlist --file MainStoryboard --file Localizable

--key: Keys of the strings to be translated. Multiple keys can be specified. If not specified, all keys will be translated. [default: None]
--language: Language codes of the strings files to be translated. Multiple language codes can be specified. If not specified, all files will be translated. [default: None]
--log-level: One from [progress|errors|group|string]. [default: group]
--help: Show info

Automation

You can go to Target -> Build Phases -> New Run Script Phase in your xcode project and paste xcodelocalize there. It will localize necessary strings during every build and your localization files will always be up-to-date.

Conclusion

Now you know how to quickly localize your iOS applications in many other languages.

Feel free to leave comments. Add a star to the repo if you like it.