Getting Started is the Hardest Part

Challenges of Building a New Web Application

Posted by lymestackblog on August 22, 2024

When starting a web application from scratch for a small to medium-sized organization, the initial setup can be a daunting and expensive task. This crucial phase often sets the tone for the entire project, and is filled with challenges that can impact the application's success and considerably affect the amount of time it takes to get started with, and actually finish a project.

Sure, buying templates can help, but they usually are only half-stack, meaning that they might help with giving you an attractive mock front-end, but there's still a lot of work to be done in order to integrate those templates with an API back-end.

Key Setup Components

The following is a list of things that I think to include when setting up a new application for a client:

  1. Database Setup Configuration - Any web application of any decent size has a database of some sort to store and query its data. While there are many databases available on the market, I prefer Microsoft SQL Server. It comes in many editions, its developer tools (SSMS) are mature (I've been using it since year 2000) , and the SQL Express edition is free for production use for databases up to 10GB in size. If you program efficiently, this can go a long way. It's also worth mentioning that it can run on Linux and macOS with the help of Docker. Lastly SQL Server is well supported and the developer community is large.

  2. User Authentication System - Perhaps I am biased, but this is the absolute worst part of web application development for me. This seemingly trivial task has tied me up for weeks on-end and has added a few grey hairs to my beard. It literally took me over a week to get Entra ID authentication working in my Angular / .NET WebApi web app, navigating through multiple outdated tutorial after tutorial, until I finally found one that finally worked. What a pain! That said, while using local accounts for security was easier and the way of the past, cyber-attacks are becoming more and more sophisticated and this painful exersice has become a necessary evil. Adding support for a single-sign-on (SSO) provider provides added security such as multi-factor authentication (MFA) using SMS messages or even more preferably, an authenticator app. Plus, there's the added benefit of not storing sensitive user passwords in your app database. There are many providers to choose from, but I feel a good choice is Microsoft Azure Entra ID platform for authentication. Like SQL Server, it's widely supported and available from Microsoft.

  3. Error Handling & Reporting Mechanisms - Errors happen. They're unavoidable. When they do, it's important to get out in front of the issue before the problem becomes more widespread. This also gives you the opportunity to reach out to users, perhaps even before they submit a terse support ticket, turning frustration into delight. When an error happens, first you need to be able to communicate to your users that errors are happening. Almost never just supress the error unless you're absolutely sure that the error has no consequence. In the case that it's a server error (500-level error), you should never present your user with any details about the error, but provide them with a generic message letting them know that someone has been made aware of the issue. Ask the user to try again later or provide a link or email address for further support. In the case of a user or request error (400-level error), you can provide some guided feedback to the user to allow the user to try again or give them explanation for why their attempt didn't work. Lastly, in the case of server errors, you need to have a mechanism that notifies an administrator or developer (via email is good unless the error is email-related) with error details, such as the request URL or stack trace.

  4. Application Navigation Structure - Typically app navigation menus start out hard-coded, but as apps grow and more user roles / functionality is introduced, this sort of thing will end up in a configuration file or database so that these menus can be more easily dynamic. For example you may want to hide menu options for users that are not in a particular role. A good default example of this would be the Admin menu. Non-administrative users should never see the menu or know it exists. Other times, you may want to attributes to a navigation menu item, such as show a notification count badge next to an item or add a dividing line to appear after it. As these features are added, a navigation menu UI needs to be provided that will allow for editing and sorting of menu items by an administrator.

  5. Mobile and Printer-Friendly UI Design - Always keeping in mind that your web app could be accessed from a mobile device like a cellphone or tablet. You'll want to implement a responsive design so that content appears gracefully on any device. If your app is heavy in reporting or accounting transactions, it's likely you'll want to support printing your reports to paper or PDF. In order to do this, it's useful to implement CSS print media queries so that you can specify certain elements to print (or not print) when a user invokes the browser's built in print functionality.

  6. Automatic Email Notifications - It's inevitable that your application will require some way of being able to notify users about certain events that happen in the app. This could be for anything from payment confirmations, welcome messages or any other sort of workflow progress or completion. Often times, the web app's owner will also want those emails to be branded with their company name and logo or want to be able to include some generic information in the footers of their emails such as links to their marketing website or social media platforms. To do this, you would need to build in a mechanism to be able to define the email template message and add tokens to merge data into the emails. Sure, you could probably use a 3rd party email campaign manager, and there is certainly a time and place for those, but often times that can be over-kill for simple messaging. Plus, the price for these online services seem to be ever-increasing over time.

  7. Email / SMTP Setup - During development it could be a dangerous pratice to send emails from your app running in a local development environment. If you aren't careful and if the right safeguards aren't in place you run the risk of sending test emails to actual live users potentially causing alarm and confusion or even bringing harm to the brand of the web app. In the old days, I would have to cumbersomely comment out code or create configuration settings to disable these messages from being sent out via SMTP. To avoid this risk, I implement a trick where all emails that are sent out via the API get caught in a folder on the server called a SMTP Pickup directory. Only in production should you change a configuration to point to a live SMTP server.

  8. Email Logging - For auditing and debugging purposes, you'll likely want to be able to keep a log of all emails that go out through the site. In order to allow for admins to self-service, you'll want to provide a UI to be able to see the message via the web app's admin interface. It's likely they will want to export the meta-data too.

  9. Activity Logging - Again, for audit and debugging purposes, your site's administrators will also want to see when key things happen in their system. Some common examples might include when a user logs in or when a payment gets accepted. You'll want to create a central area where logs can be stored and an interface for site admins to be able to report and filter on certain activity logs. Activity logs can also contain fields for meta data including human readable notes, JSON data, and reference data that can be used to link data to your business entities in custom reports. Again, the data will need to be exportable for further analysis by admins in spreadsheet programs like Excel.

  10. App Health Dashboard - As your database and file systems grow over time, often times size quotas and limitations don't become an issue until a limit has been exceeded resulting in things suddenly stopping work properly in your app. While this is one of those things that can probably be hedged off for a few months or even years, this will eventually happen, so why not get out in front of it before it does?

  11. User Communication Features - You will want users to have an easy place to be able to submit feedback and report bugs. For this, create a feedback link that is prominently visible so that it's obvious as to where a user can submit their feedback at any time. Administrators will also want the ability to push communication out to their users by being able to display one-time notices that might warn users about upcoming system maintenance downtime or announce a new feature. Administrators might also want a way to more prominently display notices to their users without users having to refresh their browsers. Such a need might be to announce an office closure due to a holiday, an environmental emergency or system availability issues. This will decrease the number of support inquiries that get submitted as a result of some sort of widespread issue. You'll want to provide your administrators with a way that they can easily do this without having to call a developer in to intervene. Ideally, any notice posted will be allowed to have an expiration date so that they can disappear without an admin having to turn off the notifiation manually.

  12. Centralized Search - As your core features in your app grow, you will want to provide users with a single location in your application where users can search for features, users, customer names, account numbers, or whatever custom entities you build for your business or client. This search should be a simple text based search that can deliver a variety of results.

Phew, that's a lot! Some things can probably be built as-you-go, but every large app that I have written has contained or needed this level of functionality by the time it got to maturity. I can't really say that I know exactly how long that I think it would take to build such a foundation, I would estimate if it were just myself from scratch, it would take about a month if not more. How long do you think it would take you?

Common Pitfalls

While tackling each of the items in the aforementioned laundry list of administrative features, a host of challenges come accompanied with this workload when starting from scratch:

  1. Tight Timelines: Often times there is a hurry to get started with core functionality of the application without laying the proper foundation. This leads to a path where lots of shortcuts are taken to "just get something working" and just kicks the can down the road introducing bugs and technical code debt where you're committing yourself to spending time to fix temporary solutions that will be more complete and scale better.

  2. Increased Costs Initial project setup takes a lot of time. Depending on how you charge your client (hourly vs fixed cost), this time it takes to develop the foundation and administrative features for your app could be cost prohibitive for a customer or cause you to lose the contract to a competitor who might not be starting from scratch.

  3. Unpolished Appearance: The focus on functionality can result in a less-than-ideal user interface in the early stages. If multiple developers are involved, you also run the probable risk that portions of the application built by different developers could look pretty different from one another.

  4. Delayed Core Functionality: Most, if not all of these tasks must be completed before developers can focus on the application's primary features. This means weeks or even months of project infrastructure development will set you back that much time in getting the actual custom application developed.

  5. Security Oversights: In the rush to get the application running, security measures are sometimes treated as an afterthought rather than a priority.

All of the challenges and risks associated with starting a project from scratch can significantly delay the delivery of an application, increase costs for your customers and erode user confidence and trust in your web application.

Strategies for Success

When starting a web application from scratch, you should employ the following steps to mitigate risks and tighten timelines:

  1. Prioritize Planning: Allocate sufficient time for the initial planning phase.

  2. Use Proven Frameworks: Leverage existing frameworks and libraries to accelerate development and improve reliability.

  3. Implement Agile Methodologies: Adopt iterative development processes to catch and fix issues early.

  4. Focus on Security: Make security a priority from day one, integrating it into every aspect of the application.

  5. Balanced Approach: Strike a balance between functionality, aesthetics, and performance in the early stages.

By understanding these challenges and implementing strategies to address them, development teams can lay a solid foundation for their web applications, setting the stage for long-term success.

Or.... Check out LymeStack

LymeStack is a web applicaton template and toolset I developed for myself to help me with laying all of the foundational groundwork that are described here in this article. LymeTools are the developer tools I created to help me to instantiate new instances of apps for me and my clients. It also helps me to eliminate repetitive CRUD coding when it comes to building core app functionality. This stable app template is a crucial part to being able to allow myself to take a vacation as a soloprenuer.

Conclusion

As a soloprenuer, I can't afford to start from scratch every time I take on a new client. Smaller businesses typically have tighter budgets, so if I were to have to start from scratch every single time I started a project, the cost and time to set up could make me less competitive and the client might run out of money before we even get started with implementing their core functionality. I built LymeStack as a few sloppy console apps that would automate much of my repetive tasks. I figured that if they were of use to me, they could be of some use to someone else. Almost 8 months ago, I tried getting an instance of the app up and running on a colleague's local computer and the process still took us several days of back-and-forth to get things working. That's when the LymeStack officially started by consolidating all of these sloppy tools into a more refined developer experience. If this intrigues you, please check our our Getting Started Guide to activate a free trial of LymeStack and get an application running on your local dev environment in an hour or less (YRMV).