Forem: Arpit Mohan

Appsmith's Deployment Architecture

Arpit Mohan — Wed, 14 Jun 2023 16:01:57 +0000

Appsmith is a turnkey solution to building internal apps in the cloud. It’s a complete workbench for building graphical interfaces and tools that connect to your existing data sources, and it integrates with popular third-party services for communication, collaboration, and commerce. Appsmith is also the community behind this project, comprising the company that invests in and guides the overarching development of the platform, the open-source contributors who help us ideate and implement, and our end users.

This article serves as an introduction to the Appsmith platform for technical readers who want to get to know how Appsmith works under the hood by examining the architecture behind our deployment binary and the problems this architecture choice solves. Whether you're looking to contribute to the Appsmith platform, wanting to build with it, or just interested in the technical considerations you might need to make for your own projects, this article will give you a solid understanding of the platform.

Appsmith’s open-source philosophy and modular architecture

One of the major contributing factors to the structure of our codebase is the open-source nature of Appsmith. We think that open source is the best way to make software that naturally evolves to meet its community's needs for three primary reasons:

Code quality: With more eyes on the code, the quality is greatly improved. Developers are encouraged to be more conscientious about their code, and mistakes that do make it into the repository can be spotted by others and fixed before they enter production.
A strong ecosystem: Community suggestions and contributions mean that our platform is always on the leading edge, responding to ever-evolving user requirements for functionality and integration.
Longevity: For the two reasons above, open-source projects are also durable — the platform and ecosystem surrounding them are public property to which access cannot be revoked, making them a safe investment for organizations to base their toolchains and workflows on.

A project as complex as Appsmith must make architectural considerations to ensure that the project can be contained within a single manageable codebase. Teams and contributors need to be able to work on different features without stepping on each other's toes, especially when they are spread across the globe.

To address this, our codebase is well documented and heavily modular, with a strict hierarchy of directories and ownership, all contained within a single monolithic repository. This concept is reflected in our deployment architecture — a single container comprising all of the moving parts to make Appsmith work.

What does Appsmith’s deployment architecture look like?

Appsmith is based on industry-standard technologies to provide front-end and back-end functionality organized in a single codebase. We deploy as a single Docker container which encapsulates:

The Appsmith Java back-end process
The NGINX server
The real-time service (RTS)
The MongoDB server
The Redis server

Appsmith’s components and architecture

We call this the “modular monolithic” architecture. A single Docker container powers the whole application, making it easy to install. All dependencies inside the container are under our control, which makes updates easy to implement for developers and more reliable for end users.

The deployment challenges this architecture choice solves

Appsmith wasn't always shipped as a single binary. Originally we shipped each component individually — one for the Java backend process, one for NGINX, one for MongoDB, etc. — totalling five Docker containers that you had to install to get up and running.

This lead to several problems for the end user, which then became problems for our developers to solve:

Problem #1: Complexity

Running a separate container for each piece of technology that underpins Appsmith made sense initially: each was a standalone program, so it followed that it should have its own container. This made deployments complex: the Java back end needed to talk to MongoDB and Redis, NGINX needed to talk to the back end, and the RTS needed to talk to the backend and NGINX. Installation wasn't just a matter of deploying containers; they all needed to be configured to communicate with each other.

With this multi-container architecture, our early users only had a 30% success rate on their installations. This deployment mess would also only grow with time if we decided to swap out or add components to the Appsmith platform.

Problem #2: Compatibility and upgrades

Running on outdated dependencies would be to the detriment of Appsmith — we want to be compatible with the latest databases and leverage the performance and functionality gains from the open-source projects we’ve built on. With a multi-container deployment architecture, every time we updated one of our components (for example, moving to the next major release of MongoDB), our users would have to manually update their docker-compose.yml file, redeploy, and hope that nothing breaks. If we updated all of our components, this would mean upgrading five containers.

Keeping multi-container deployments up and running can be an annoying task

It was unrealistic to document the changes users would have to make to their Docker configuration and expect them to follow through with them to remain up to date. We could see immediately that it would result in many users never updating and some even spending that effort migrating to a platform with a more reliable and predictable upgrade experience instead.

Problem #3: Bash scripts are unintuitive

In an attempt to smooth out the multi-container deployment and upgrade process, we wrote a shell script, unimaginatively called install.sh. It would ask you a sequence of questions about your environment and generate a docker-compose.yml file. Running this file would configure the multiple Docker containers required to run Appsmith and set up all of the connections between them for you.

While install.sh worked on a technical level and was an elegant piece of scripting, it did not work on a user-experience level.

Bash scripts for deployment do not inspire confidence. Users rightfully see them as a risk, and they give the impression of being a “hacky” solution — no matter how elegant they are. There is also the risk that inconsistencies in user environments could lead to unintended side effects from a Bash script (not everyone reads through them before running them). Something as simple as a user storing files at an unexpected path could result in accidental overwrite or deletion.

The other issue we foresaw with Bash scripts, especially as our user base grew, was a lack of control. Updates or changes to a user's system could require manual maintenance to keep Appsmith’s containers properly configured and communicating. This, again, would only become a bigger mess as time went on and we upgraded or replaced different Appsmith modules (for example, upgrading the version of MongoDB or swapping Redis for a different ephemeral data store). It would be almost impossible to keep our Bash script updated for every encountered deployment scenario and allow for consistent updates from different prior releases.

Collectively, these problems were a significant barrier to entry for any user looking at Appsmith. A solution was decided on — consolidating to a single container that was easy to install, easy to upgrade, and not reliant on free-roaming scripts being run on the user’s system.

The decision to implement a single-container architecture, and how we did it

Our decision to deploy a ”fat binary” — a single Docker container comprising all of the Appsmith code and dependencies — comes from both the need to meet our users’ expectations for a smooth deployment experience and our own frustrations with overly-simplistic hosting paradigms, which, ironically, are often implemented to replace similarly frustrating complicated setup processes.

Over-simplified installation processes do not allow for user choice around privacy, security, and performance. Users need to be able to specify how and where data is stored, choose what information is made available to other systems, and make decisions about the performance (and resulting costs) incurred by their infrastructure. Removing these choices in favor of a quick start is not a workable trade-off — there needs to be a balance that offers users a streamlined installation experience, with the option for granular configuration.

It’s apparent from user feedback that our current solution achieves this, but it does fly against convention, so we had to make sure our decision to implement it was fully informed, justified, and tested.

Reconsidering Docker conventions

When containerizing an application using Docker, it is generally considered best practice that each process needed for the application be run as a separate container, then connected to others as required. As discussed, this would currently require five total containers for Appsmith and its dependencies to run.

Our single-container solution breaks this convention. While the prevalent perception is that Docker works best when running and managing one single process, we found that the advantages of delivering all of our code in a single container outweighed any potential disadvantages. This decision was not taken lightly. We did not want to compromise the performance or stability of the platform in production, so we fully researched and tested the implications of deploying to a single container, adopting the credo:

You can break the rules as long as you know why they were made.

If you fully understand why a rule or best practice exists, your justification for breaking it is fully informed. Every problem is different, and blanket rules shouldn’t prevent a practical, reliable, and secure solution.

Our goal was to abstract work away from users who had no requirement for extra customization, like hosting their own databases and services to support their Appsmith deployments. We broke the rule because, after considering the reasons for the rule, we found that they didn't apply to our use case. Unlike the majority of Docker usage scenarios we do not need to scale and monitor services independently or segregate services for security, so we decided the fat container approach was appropriate. Additionally, GitLab does the same thing and we thought,_ if it's good enough for GitLab, it's good enough for us!_

This meant that instead of using Docker to isolate processes, we used it to isolate the whole application, repurposing Docker to provide a single executable binary for end-user convenience rather than process isolation for DevOps purposes.

Maintaining attention to detail

This design doesn’t exclude users who do want to host their own MongoDB, Redis, or other services and connect Appsmith to them. The Appsmith container is smart enough to recognize when an external MongoDB or Redis server is configured and doesn’t start either process inside the Appsmith Docker container.

We are developers first, building a developer-first experience at Appsmith.

-- Quote from the Appsmith development team

This “smart” behavior is a result of our attention to detail. We want users to delight in the small quality-of-life features we have included in Appsmith — features that we’ve added to address our own day-to-day inconveniences and that we know will be appreciated by other developers. We didn’t want an architecture that would limit the ways that we could extend the platform in the future, whether at its foundations (affecting deployment) or higher up (affecting the end-user experience).

An example of one of these quality-of-life features that affects both those deploying and maintaining Appsmith and those using it is our implementation of SSL. When you configure a custom domain for your instance, Appsmith will attempt to provision an SSL certificate from Let’s Encrypt. If it succeeds, the instance will start with HTTPS enabled on the web server, and redirect all requests with http:// URLs to https://. If the Let's Encrypt provisioning fails, the instance starts with plain HTTP, without displaying worrying errors or browser warnings that users may be encouraged to ignore, setting dangerous precedents.

Again, in keeping with our philosophy of making setup as simple as possible but still giving advanced users full control of their infrastructure, it is also possible to supply your own custom SSL certificates.

Appsmithctl is another example of our user-centric features. It provides a convenient interface for managing and maintaining your Appsmith instance and allows you to back up all of your Appsmith data with a single command:

docker-compose exec appsmith appsmithctl backup

Regular backups are the most important practice for ensuring continuity for any organization that relies on their digital assets, so we wanted to make sure a programmatic way to do this was available out of the box.

Implementing process management in the Appsmith container

Supervisor’s web and CLI interfaces

Moving everything into a single Docker container means we can't use Docker to monitor the status of each component. Instead, we use Supervisor, a popular, lightweight process manager. This has proven effective — when given a list of things to run, it will run them, start them again if they crash, and collect their logs in case further troubleshooting is required.

Supervisor comes with a web interface with a graphical view of all the processes it’s managing. We expose this interface, so you can see what processes Appsmith has launched internally, monitor performance and resource usage, and even restart services manually if something gets stuck.

All of the features exposed through the Supervisor web interface are also available on the command line from outside of the container. For example, the following command will list the status of each running process:

docker-compose exec appsmith supervisorctl status

This allows for programmatic access, useful for advanced users who may want to further orchestrate and automate the running of their Appsmith instances.

Process management with Supervisor works as follows: When the Appsmith container starts, the processes that need to start with it are identified. If external MongoDB or Redis databases are configured, those services inside the container will not start. The Java backend process, the Node.js RTS, and NGINX will always start. For each of these identified processes, the container's entry-point script — invoked by Docker when the container is started — generates a set of Supervisor configuration files containing only the services that need to run. The configuration for each service contains any environment variables required, the command to launch the service executable, and logging details.

Again, this illustrates how the move to a single container has not impacted user choice or control over the different components of Appsmith; it just abstracts decision-making away from the majority of users, who just want to start using the platform.

The effects on deployment for end users

A single container makes deployment fast and hassle-free

The proof is in the numbers: the abysmal 30% installation success rate for our multi-container deployment architecture has gone up to a 99% success rate with single-container Appsmith deployments.

Appsmith is now a single Docker container that installs with a single command (or a single click, if you're deploying to the cloud). Hosting and management complexities are largely hidden, so that you can focus on building your own apps, not trying to fix ours.

_We loved that we could deploy Appsmith on our local instance and build an app. For us, it was an important concern because it would involve our production database credentials, which we were unwilling to share.

It’s so easy for anyone to set up in the first place. It simply went directly to the AWS marketplace, selected their pre-existing supported AMI, and spun up an EC2. Instantly it was up and running._

-- Feedback from user

Seamless updates

Updates are now seamless as well. Optional automatic updates can be enabled and will be installed during a specified maintenance window. Recently we upgraded to MongoDB v5 within our deployment container — and it was seamless for our end users.

We can now update all of the components in Appsmith, and even add new microservices, with full confidence that we won't break anything on our users’ systems.

Kubernetes support

The single-container approach has also made supporting Appsmith on Kubernetes much easier. This was a highly-demanded feature in our community, and the reasoning resonated with us well enough that we prioritized Kubernetes support.

One of the primary reasons for using Kubernetes (scalability aside) is rolling deployments. Containers can be dynamically upgraded, or deprovisioned and reprovisioned with updated code, with enough containers always online to meet current demand, resulting in zero downtime.

An Appsmith upgrade can take up to 20 seconds — fine for most users, but too long in high-availability scenarios — and can still fail in edge cases. With Kubernetes, nodes that fail to upgrade or become unresponsive are simply not used, and can be deprovisioned or troubleshooted. The single-container approach we have chosen makes managing an Appsmith Kubernetes cluster far easier than it would be if all of the components were hosted in separate containers, giving our users additional reliability through redundancy.

How Appsmith strives to earn and maintain community trust

All of the above work is towards one goal — an easy to deploy, production-ready internal app studio that lets developers focus on their business logic and get on with their jobs. This requires a community providing their requirements and ideas, and that requires trust. At Appsmith we’ve worked hard to earn this trust with our users and open-source community. As demonstrated by our architecture decisions, we maintain this trust by ensuring we pay full attention to our core responsibilities and our communities needs:

Security and openness

To ensure the security of your vital data, Appsmith can be hosted wherever you are comfortable hosting it — from the public cloud to your own VPC, or on-site. Our monolithic container lends itself to this perfectly.

Because we are open source, our code can be vetted by anyone, and we are transparent about our security practices so that our users are informed.

Performance and simplicity

You don't have to run Appsmith on professional infrastructure. You can test and run it with full confidence in any supported Docker environment. Our team members use Appsmith hosted on our laptops, home servers, affordable cloud hosts, and even high-redundancy clusters. Wherever you are deploying Appsmith, we make sure that the process is as simple as possible.

Reliability and control

Our open-source code is of high quality and is contributed to and reviewed by both our internal teams and community volunteers. We keep you in control of your Appsmith deployments, so that you can decide exactly where you want your data stored and whether you want automatic updates to run. This means you're never caught by surprise by unexpected changes or the loss of data stored in-container. We take user control and choice seriously.

Appsmith: a rock-solid platform that we can all build on

When building an application, finding the balance between practices that benefit the developers and the end users can be difficult. Developers' decisions about the architecture and underlying technologies of an application can either expand or restrict the eventual feature possibilities of a platform.

This extends to deployment. Deploying Appsmith as a collection of connected microservices hosted in separate Docker containers, while beneficial during development and debugging, did not make for a pleasant or reliable experience for users running our tested application releases. Our move to a modular monolithic architecture and the further decision to deploy Appsmith as a single Docker container have improved both our developer and our end-user experience.

If you're a developer interested in contributing to the Appsmith open-source project, our contribution guidelines will get you started, and you can join us on Discord. If you build internal apps and are interested in what Appsmith can do to streamline your own development process, our tutorials and user documentation will get you started.

Appsmith Hacktoberfest Week 1 Update

Arpit Mohan — Tue, 06 Oct 2020 04:57:14 +0000

It's been a busy week at Appsmith, thanks to Hacktoberfest. There's no better way to end this week than by thanking all the developers who chose to contribute to Appsmith during this period. We are a small team of developers and this ❤️ means a lot to us.

Over the week, we've merged in 16 Pull Requests from contributors. That's insane!

If you'd like to get in on the action, Appsmith is running a special challenge during the month of October where you not only get swag for contributing a valid PR but also a customized mechanical keyboard; for inviting other users to contribute to our repository.

Check out details of the Appsmith Challenge here.

Here are the contributors (in no particular order) that I'd like to mention & thank.

Also, a lot of folks improved our documentation. We've merged 20 PRs just for our docs. Some of the top contributors to our documentation are:

Thank you everyone for being a part of this project. Look forward to more pull requests & contributions.

Happy Hacking!

PS: Join our Discord channel and participate in the Appsmith Challenge and become a part of a welcoming community.

Hacktoberfest Kickoff Event

Arpit Mohan — Thu, 01 Oct 2020 10:28:03 +0000

Hacktoberfest is a month-long celebration of open source software. As developers, we stand on the shoulders of giants. Each year, in the month of October, as a community, we pledge to feed this giant.

Contributing to open source projects is fun and rewarding. At times, it can even be daunting to get started. Lots of people believe that only code that implements large features matter. That's not the truth. No contribution is too small — bug fixes and documentation updates are valid ways of participating.

I'm doing a livestream on Appsmith's Discord channel today at 8:30 AM PST / 9 PM IST to help you get started and show you how to open your 1st PR. This 30 minute stream is a tutorial for new and seasoned developers.

The agenda for the livestream will be:

How to find the right projects to contribute to
How to open PRs
How to communicate to ensure your PRs get accepted
Best practices when contributing to open source

As the lead maintainer of Appsmith, I'll use our repository as an example of how to contribute.

Shameless plug: Appsmith is an open source low code product to build custom internal tools and admin panels. We are a welcoming community & have lots of issues that first time contributors can pick up.

Appsmith $1000 Bug Bounty Program

Arpit Mohan — Fri, 18 Sep 2020 14:18:20 +0000

Above Them is a bug bounty program where you get rewarded for reporting the hairiest bugs that you face with the open source project, Appsmith.

appsmithorg / appsmith

Platform to build admin panels, internal tools, and dashboards. Integrates with 25+ databases and any API.

Organizations build internal applications such as dashboards, database GUIs, admin panels, approval apps, customer support dashboards, and more to help their teams perform day-to-day operations. Appsmith is an open-source tool that enables the rapid development of these internal apps. Read more on our website.

Installation

There are two ways to start using Appsmith:

Signup on Appsmith Cloud.
Install Appsmith on your machine. See the installation guides below.

Installation Methods	Documentation
	Docker (Recommended)
	Kubernetes
	AWS AMI

For other deployment options, see the Installation Guides documentation.

Development

To build and run Appsmith in your local dev environment, see Setup for local development.

Learning Resources

Need Help?

Contributing

We ❤️ our contributors. We're committed to fostering an open, welcoming, and safe environment in the community.

📕 We expect everyone participating in the community to abide by our Code of Conduct…

View on GitHub

These could be performance issues, documentation problems, small niggles or even a UX issue you faced. File away with no holds barred.

The most number of bugs reported before 30th September, 2020 earns you $1000.

What is Appsmith?

Appsmith is a low code way to build internal tools. It's the only open source alternative to Microsoft Power Apps, Salesforce Lightning platform, Service Now platform and many more.

With Appsmith, you can:

Create a page using pre-built UI components like table, charts, map viewers and forms.
Connect the UI components to any REST API or databases like MySQL, Postgres, and MongoDB. Write any logic in JS.
Deploy the interal tool to a custom URL and invite users to sign in with their Google acounts.

Why Participate?

Recently, one of our users expressed their love & frustration with Appsmith on Twitter.

// Detect dark theme var iframe = document.getElementById('tweet-1305804208944357376-191'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1305804208944357376&theme=dark" }

We are an open source project because we believe that software built in the open becomes better. This user's tweet clearly shows that our code has issues and as a small team we can't find them all.

Also, lots of folks want to contribute to OSS but they aren't developers or just don't know how to begin. That's why we are starting our journey by rewarding users for simply reporting bugs.

If that wasn't incentive enough, we have some prizes to sweeten the deal:

1 Grand prize for most number of qualified bugs

$1000 USD gift card or equivalent
Earn an Appsmith badge
Recognition on our README page

10 Runner up prizes

$50 USD gift card or equivalent
Earn an Appsmith badge
Recognition on our README page

You need to report a minimum of 2 bugs to qualify.

How can you participate?

Try out the product by checking out our Getting Started guide.
Report any bugs by creating a Github issue on this repository.
Label those issues with the tag above-them to help us identify these issues quickly.
Join our Discord channel and claim your prize.

Who is eligible?

Everyone is eligible for this program.

You don't necessarily need to be a developer to participate. Infact, most of our insightful bug reports in the past have come from non-developers.

One open source project for admin panels, CRUD apps, & internal tools

Arpit Mohan — Fri, 21 Aug 2020 13:44:38 +0000

We’ve all spent time on building internal tools which could be CRUD apps, admin panels, or complex workflows.
These kind of internal tools are used for:

Analytics and reporting
Customer data views for sales & support teams
Configuration managers for client-visible UI used by technical and non-technical people
Multi-step data workflows which involve multiple participants(like content moderation tools or customer KYC at fin-tech startups)

These tools often aren’t very interesting to build because of the repetitive work involved like building UI, writing CRUD APIs, setting up authentication, & managing deployments. I decided to create Appsmith because I couldn’t find a project which did most of the work for me and also easily customizable.

How does Appsmith work?

First setup Appsmith using Docker. Read instructions here for a 2 min setup process.(https://docs.appsmith.com/quick-start#docker). Or try our online sandbox
Go to https://localhost or your machine’s public IP to see the login page. online sandbox.
Create a new application and name it.
Connect to a database or API. Today MySQL, Mongo, Postgres, and REST apis are supported. The gif below shows me connecting to an API.
Go to the canvas section and choose a UI widget. Appsmith ships with 16 components like tables, different charts, map viewer, forms, etc. In the example below I’ve used a table component.
Modify the table property to display your query results by writing {{queryname.data}}. You can code in JS and use Lodash functions inside {{ }}.
Trigger an action through events like onClick, onTextchange, onSelectedrow, etc for CRUD operations.
Click deploy to see your app in a URL. (You can set up a custom domain in the setup script)
Invite users after assigning them a role. They can sign up via a form login or with their Google/Github accounts. Make your app publicly viewable to allow access without a login.

So this is how you build a simple app in less than 10mins. Access an app I built on Appsmith here.

Appsmith is the first open source project to build internal tools. If you like the project, please star our GitHub project.

What features should we add to Appsmith?

TL;DR: Appsmith is an open source framework to build apps for analytics, workflows or CRUD operations. Replace all your internal tools with one project. See GitHub repo or try an example app here.

Open source + proprietary code structure

Arpit Mohan — Tue, 16 Jun 2020 06:57:19 +0000

I am considering open sourcing a project that I've been working on. Ideally, I'd like to create a hybrid structure that allows for a community edition & enterprise edition (much like Kafka, Gitlab etc). The community version will have the basic features while the enterprise edition will have some premium features and workflows.

I'd love to hear from the community on how do we, as a team, split the code and/or how do we structure the code to keep the community versions & enterprise versions independent, clean and maintainable.

For reference, the technologies we use are Java11 & React.

Look forward to learning from your responses.

Lessons learned while working on large-scale server software

Arpit Mohan — Mon, 06 Apr 2020 13:00:21 +0000

TL;DR notes from articles I read today.

Lesson learned while working on large-scale server software

Always have a plan for worst-case scenarios for error conditions, and find a general solution, such as automatically shutting down all operations and return an error code with when to retry or a contact to call.
Document your decision making and add idempotence wherever possible.
Approach debugging in a scientific way: first, gather data, form the right hypothesis and design an experiment to prove it, and then apply your fix; use tools to dig deep into traces and memory without stopping the system.
Impose a strict implementation of Postel’s Law: Be conservative in what you send, be liberal in what you accept.
Be wary of a major deployment that seems to go smoothly. Errors are inevitable and the bigger and quieter the error, the more dangerous they are. If you are not sure how to handle an error, let the system crash. It makes it easy to catch and correct errors.
Be prepared to restart the entire system from a blank slate under heavy load.
Notice technical decisions and components that have global effects, not just global variables.
Build channels for persistent communication as new people are onboarded and leave teams. When building systems, do not assume operators will do things correctly and give them the tools to undo mistakes.

Full post here, 10 mins read

Being a great engineering mentor

Be ready to listen. Your mentee should always feel free to ask you questions, especially in the first few weeks of onboarding.
Help anchor them socially in the new place. If possible, carve out a weekly team ritual.
Let them feel safe enough to pursue novel solutions by showing them how to evaluate risks within the context of your organization and team.
Explicitly inform your mentee of technical safeguards in place as well as providing non-technical assurance of help with failures.
Understand their strengths and weaknesses, and encourage as well as challenge them technically with tasks that let them level up while having fun, gradually adding more unfamiliar or challenging jobs. Offer code hints but don’t unnecessarily prime them with warnings of difficulties ahead, and occasionally add stretch goals and praise their resolution to build confidence.
Have 1-on-1 discussions and reinforce when you notice they are doing a great job while challenging them to do even better and share business context they might not readily see, as well as the engineering context of their project predating their on-boarding.

Full post here, 8 mins read

How to feel less overwhelmed as a developer

Arpit Mohan — Fri, 03 Apr 2020 13:00:29 +0000

TL;DR notes from articles I read today.

How to feel less overwhelmed as a developer

When you feel overwhelmed, either there is too much going on at once or you are overstimulated. Refocus and reprioritize.
Identify the specific problem - be it too steep a learning curve, too much information incoming, too many responsibilities, peer pressure or your own expectations of yourself.
Zero in on your key goals, set your boundaries, focus your ambitions, and recognize what’s not really relevant to you.
Find a process for self-education. Don’t try to memorize everything, learn where to find the right information. Make a list of what you don’t know, and add to it every time you come across a new idea or a skill you don’t have. Sift through the content and establish your key resources so you aren’t overwhelmed.
Beware of getting overwhelmed by other people. Make sure you have a balanced perspective on social pressure. Know that a lot of people write bad code, even great developers in great companies. People have different priorities and you don’t have to keep up with theirs. Remember that people will write about what is possible but you don’t need most of it on a day-to-day basis.
Work smarter by spending time on core skills like problem-solving, critical thinking and testing. Use proper project management tools to plan, manage tasks and track bugs. Take breaks for fresh air, exercise, and conversation so you don’t lose sight of the big picture. Ask your community for help with good resources, pointers or support with your workload.

Full post here, 9 mins read

Don’t be a jerk: write documentation

Documentation can be minimal and yet helpful. Take whatever you have in volatile formats (email, chat logs, shell I/O) and paste it into more durable ones (README files, diagrams, websites, FAQs, wikis).
Document based on your audience:
1. For newcomers, focus on what it does, why you wrote it, who should be using it and for what, how it should be used (how to build, configure, run and get started), and where additional information may be found; do not display the source.
2. Regular users could do with a reference manual, examples, EDoc/JavaDoc/Doc, wiki or website, and API descriptions.
3. Contributors should have access to the source repository, as well as project structure and architecture (where to find out about specific functionalities and where new features should go), the project principles, tests, issues, and a roadmap.
An easy way to get started is to imagine you are talking to a new user. Then vary the user and add different scenarios (of their business context and experience/knowledge, budgets) to expand the documentation until it is comprehensive. Finally, you might split it up into categories for different people or reimagine/format it for different media/platforms.
Another approach is to find a problem a user might face and show them how to solve it.

Full post here, 11 mins read

Get these notes directly in your inbox every weekday by signing up for my newsletter, in.snippets().

How to make decisions in the face of uncertainty

Arpit Mohan — Fri, 03 Apr 2020 05:21:28 +0000

TL;DR notes from articles I read today.

Three types of risk: making decisions in the face of uncertainty

Fatal risks can kill a company, so you need to be extra careful to watch for them as your company grows and ages. It is easy to get complacent but there is no recovery from such decisions gone wrong.
Painful risks have lower but significant repercussions: missing a key goal or losing key people. But you can recover from them.
Embarrassment risks have no significant impact beyond just what the name states. You just need to acknowledge the mistake, change course and move on.
Another way to think about risk is Jeff Bezos categorization of decision making into Type 1 (irreversible, so spend time on them) and Type 2 (reversible, as with painful and embarrassing risks, so make the decision quickly and move on).

Full post here, 4 mins read

Four magic numbers for measuring software delivery

Lead time to validate, design, implement and ship a new valuable thing. Consider two types of lead time: (a) feature lead time: the time to move an item from high-level requirements to feature release and (b) deployment lead time: the time from merging to master to the component being in production.
Deployment frequency, understood as number of times per developer per day you ship to production. Your deployment frequency may ebb and flow, from 5-10 on a busy day to none the rest of the week. Establish a baseline over 4 weeks: say, 1 production deployment per day on average.
Change failure percentage, ie, the proportion of red deployments, bugs, alerts, etc. Defining change failure rate as bugs per production deployment over a given period, aim for about 10% or less with medium or high-priority of customer impact.
Mean time to recovery/resolution. For mean time to resolution, aim for less than a working week.
Considering feature lead time as a key performance indicator can help you break features up and deliver faster. This might also decrease lead time per deployment.
Convert generic support tickets into bugs with customer impact implications so they can be tracked better. Make bugs more visible can also make bottlenecks in the resolution process more apparent.
Count red production deployments and production alerts as a change failure.

Full post here, 9 mins read

Get these notes directly in your inbox every weekday by signing up for my newsletter, in.snippets().

Inefficient efficiency

Arpit Mohan — Wed, 01 Apr 2020 13:00:14 +0000

TL;DR notes from articles I read today.

Inefficient efficiency

Latency (measured in time units) is the time between a stimulus and a response, while throughput (measured in deliveries per time unit) is the rate at which the system meets its goals.
Sometimes latency and throughput interfere with each other. Do you field a request and respond before taking the next request (low latency for the first customer but overall lower throughput), or do you accept the second request while processing the first for higher throughput?
You make latency/throughput tradeoffs every day and most of us are biased towards throughput. For example - you carefully plan all foreseeable architectural improvements instead of initiating the first profitable change you come across.
Instead, you should optimize for latency. For example - if preferences are likely to change between requests (high rate of change), so you can adapt, which is less wasteful.
To decide between throughput and latency, consider the cost of delay, whether you might learn something that changes your approach subsequently, and whether external factors might force a new approach.

Full post here, 4 mins read

Tips on API monitoring

Track your functional uptime with comprehensive, end-to-end testing for both functionality and performance. Simple ping tests are usually not enough to meet your service level agreements (SLAs).
Since 95% of API vulnerabilities are due to human error, add monitoring at 5-minute intervals for breaches and downtime. Integrate automated testing into every step of your CI/CD pipeline to filter out human errors and make sure you have load-testing capabilities too.
But you should beware of
- tools that perform ‘synthetic testing’ and cannot reproduce actual consumer flows.
- tools that use third-party clouds, adding another layer of insecurity to your API (have internal APIs use on-premise tools instead).
- having separate testing and monitoring solutions.
- tests that are not detailed enough for intelligent results.

Full post here, 4 mins read

Get these notes directly in your inbox every weekday by signing up for my newsletter, in.snippets().

Big myths surrounding technical debt

Arpit Mohan — Tue, 31 Mar 2020 13:00:30 +0000

TL;DR notes from articles I read today.

Five big myths surrounding technical debt

Myth #1 is that tech debt is amorphous, when in actuality it is usually a collection of many discrete problems. This means you can quantify tech debt (frequency, impact, cost to fix) on a spreadsheet or tracker and then prioritize based on impact.
Myth #2 is that all tech debt has a single cause. In fact, there are three major sets of causes (or enablers):
- Intentional tech debt, where the team knowingly took shortcuts to meet deadlines.
- Unintentional, where poor code results from inexperience or incompetence or misunderstood requirements.
- From age, where incremental enhancements and bug fixes cause a bit rot.
Myth #3 is that you should never intentionally take on tech debt. But there are three situations where it may be justified: you are building a prototype or demo module to solicit feedback on a new feature or product, time to market is critical or you are building based on guesswork and anticipate client requirements will change sooner than later.
Myth #4 is it only hurts engineers. In fact, it affects developers, product managers, customer support teams and customers, technical operations, and any executive team you may set up.
Myth #5 is that only a full rewrite can repay the debt, whereas more often, a detailed plan of incremental fixes will solve it.

Full post here, 8 mins read

Indirect benefits of building API-first

A major benefit of building API-first is agility, both digital and strategic. You are not constrained to a single usage pattern and have the basis for a variety of applications with use cases you can’t even imagine yet, offering both flexibility and reusability.
Your end-user has a better experience since APIs encourage interactivity across internal and external applications, creating a stickier, unified experience for consumers.
Building your organization around APIs creates a potential for partnerships, big and small, whether using the marketplace model (your platform allows others to build and distribute custom add-ons, in turn extending your own platform) or one where partner APIs share data with a common, collaborative goal.
Outward-facing APIs enable the growth and inception of self-sustaining developer communities, providing you with awareness, API support, product suggestions and more.

Full post here, 4 mins read

Get these notes directly in your inbox every weekday by signing up for my newsletter, in.snippets().

Feedback is not a dirty word

Arpit Mohan — Mon, 30 Mar 2020 13:00:28 +0000

TL;DR notes from articles I read today.

Feedback is not a dirty word

Without a good feedback system, pockets of disagreement can grow into resentment, distrust and eventually organizational failure. Feedback is also the only way to achieve true personal growth.
For critical feedback to be effective, give it in private and with positive intentions, be specific and factual, and use a non-violent communication format: ‘when you do , I feel because the story in my head is ’.
Set up review sessions regularly (ideally weekly) at an expected time.
Be receptive to feedback and sidestep your ego’s fight or flight response by evaluating ideas objectively and viewing feedback as a gift.
Once you have heard the feedback, repeat what you heard, request confirmation and keep asking ‘Is that all?’ until you are sure the other person is done. Finally, think objectively about the feedback and suggest an action to resolve it.
Ensure that feedback is a part of your culture and an expectation from managers. Hold weekly one-on-one meetings, with structured time in the end for mutual feedback and put it all on record.
Publicly seek feedback from your team and discuss it. As a leader, publish written feedback from other leaders for the entire company and discuss ways you are trying to improve.

Full post here, 5 mins read

Absolute truths I unlearned as a junior developer

The title of ‘senior developer’: Don’t be led by job titles alone. Value collaborative experience, being reviewed and having a mentor. Avoid an early position where you have to work alone.
Everyone writes tests: Loads of companies have little or no testing, because they have either never felt the pain of not having tests or felt the pain of having legacy tests.
We’re far behind everyone else: Beware of ‘tech FOMO’ as academic settings and conferences often cover proof of concepts rather than real-world scenarios. Dealing with legacy is normal.
Code quality matters most: Often, good enough code that works and is maintainable is good enough. Overarching architecture is more important than nitpicking.
Technical debt is bad: Disorganized or messy code is not the same as technical debt. Technical debt actually slows you down or causes errors or makes changes difficult. A certain amount of tech debt is healthy because it assures delivery.
Seniority means being the best programmer: Senior engineers need many skills, from communication and dependency management to estimation and project management. And the truth is that we all remain junior in some areas.

Full post here, 14 mins read

 
Get these notes directly in your inbox every weekday by signing up for my newsletter, in.snippets().