Overlooked topics when starting a project from scratch

When embarking on a new project, the team faces significant decisions: determining the architecture, selecting the tech stack and cloud provider, choosing the agile methodology, and picking the best delivery model. However, there are certain overlooked topics which appear during the project formation phase, necessitating swift decision-making by the team.

To avoid ad-hoc discussions that may disrupt the sprint progress, consider the following list that can help you plan upfront.

The principle of least privilege and service accounts

Although it might seem obvious, workflow bottlenecks can occur when a team lacks necessary accounts or appropriate privileges. The solution lies in describing the procedure for getting an account and identifying the party responsible for it.

A common pitfall is ignoring the principle of least privilege. Since we don’t have time to deal with missing privileges in the middle of the task, we grant them all and promise to do them later in a more granular way.  Instead, try designing access policies early in the project. 

Here are the usual accounts typically needed by the team:

• Github, Gitlab, or other SCM accounts
• AWS/GCP/Azure
• Email accounts for a specific domain
• Jira, Pivotal, or other project management system
• Postman, Swagger, or other API tooling
• Sonarcloud or other code quality checkers
• IntelliJ license
• Team communication apps like Slack, Zoom

Another common pitfall is using personalized accounts to complete system tasks. For instance, CI/CD pipelines may execute static code analysis by Sonar, authenticating with a Sonar token that belongs to a person.

Employees depart from companies and teams, causing the oversight that their access tokens may become invalid, disrupting your workflows. The solution is to use service accounts or service tokens, or register a special CI/CD email within your company domain and dedicate it to this purpose.

Monorepo or multi-repo

Decide how Git repositories are going to be structured.

• What is going to be the division criteria in multi-repo? How will code be shared between repositories?
• How will independent modules be prevented from calling each other’s internals in monorepo?

Code organization

Think about organizing the code into packages. What will be the division criteria? Possible options are:

• Layered organization (web/domain/persistence)
• Organize by feature
• Hexagonal architecture
• Clean architecture

Backend and frontend collaboration

For effective collaboration between frontend and backend developers, alignment on REST API specifications is crucial. Define an approach that solves the following:

• Frontend developers shouldn’t be blocked until a REST API is ready
• Maximize the chance that frontend developers get the accurate REST API specification
• Consider the contract-first approach where the OPEN API specification is defined first in tools like Swagger or Postman
• Consider how to validate and technically bind an implementation to the OPEN API specification

Architecture documentation

Once your architecture is not simple enough to map it mentally, you’ll have to start documenting it. Begin documenting early by selecting your documentation model and presentation tool in advance for optimal preparation. 

Possible options are:

• C4 diagrams (there are many tools out there that help you visualize C4 diagrams)
• Architecture poster (Excelidraw, Miro, draw.io)
• ADR (What format will your ADR take? How will version control be implemented? How will it be approved?)

REST API standard

Although REST API is already a standard on top of HTTP, there are some specifics that every team does differently. Discuss and document what the REST API standard in your organization will be. Consider the following points:

• Plural vs singular resource names
• How to represent actions in REST API (for instance, the action name can be part of the URL path or part of the request body)
• How to present filtering, sorting, and paging capabilities for collections
• Error response format and the level of details communicated to the developer and the end user
• Should the response be enriched with links, like HATEOAS style
• How to handle API versioning (if any)
• API documentation

Log messages format

For effective log analysis, ensure all your log messages are the same across all services. Using structured logging pays off here.

• Define what will be the structure of your log messages
• Enforce structure by using logging libraries

Resource tagging policy

Chances are that modern projects will be running in the cloud. Resource tagging policy is an important topic because it lets you organize cloud resources and track costs within defined categories. Think upfront about how you want to group your resources. Some options can be:

• Tag by the team who owns the resource
• Tag by bounded context
• Tag by the environment (dev, staging, production)

Similar to log messages, find a way to enforce the tagging policy by using shared libraries.

Versioning

 In the end, products are made from different artifacts (container images, Maven artifacts, Golang modules, Kubernetes apps, etc.). When a team creates a new feature, they will pack it into a single artifact.

Chances are, this artifact will then be wrapped in another layer, eventually resembling the complexity of an onion.

Topics to consider are:

• Will both the pom.xml and the Docker image be versioned, or is it just one of these artifacts?
• What is the source of truth for version number? (hint: Git Tag)
• What is the procedure for increasing the version number (whether automated or manual)?
• What criteria will determine when to update the version in automated versioning? In semantic versioning, which part gets updated – major, minor, or bug fix?

Teams use different strategies for automated versioning, all of which involve rules the team must adhere to when committing code. For instance, they can agree to name feature branches with prefixes like /fix/ or /feat/. Or they can use structured commit messages that will serve as decision criteria for calculating the new version.

In the project’s early stages, what topics are frequently overlooked besides the ones currently being addressed? Please feel free to share them in the comments section.