Skip to Main Content

This document describes the source code layout of projects built on top of a standardized application framework. The repository is split into a frontend and a backend folder, each with its own build and deployment scripts. By separating the frontend (client-facing code) from the backend (server-side logic and APIs), teams can iterate quickly on one part of the system without impacting the other. This modularity also streamlines deployments, improves maintainability, and supports a clearer separation of concerns.

A shared codebase across the full stack encourages a more unified development approach. Common utilities, interfaces, and architectural principles—such as consistent naming conventions and coding styles—can be adopted throughout. Over time, this consistent structure reduces cognitive overhead for developers moving between the frontend and the backend.

Repositories

At the highest level we organize around a series of repositories under a single GitHub organization – 1 to 100. The 1 to 100 organization serves as the high level organizing structure for all the projects associated with the 1 to 100 organization.   We then have a series of repositories under this organization:

Principal documentation for each repository is found in the WIki associated with that repository.

Principal tasks lists (tickets, release schedules, sprint schedules) are found in projects associated with each repository.

Frontend Folder

The frontend folder encompasses all the client-side code for the web application. Written in React and TypeScript, it follows a component-based architecture to encourage reusability and maintainability. The folder also leverages Material UI for pre-built, reusable UI components, helping teams implement interfaces that are both visually consistent and customizable.

Because this folder is dedicated strictly to client-facing functionality, it is structured to streamline the development of UI features. By compartmentalizing code into directories such as components, controllers (where relevant on the client), and utilities, developers can easily locate, update, and share logic across the application. TypeScript interfaces placed here (or in a shared folder) also help ensure typed data contracts between frontend and backend layers.

config directory

This directory holds configuration files that govern the frontend’s behavior, such as environment variables, feature flags, or references to external services. These configurations can be exported via Firebase Remote Config in production, ensuring that new settings can be toggled or updated without requiring a complete redeployment of the application. It provides a single source of truth, minimizing the risk of mismatched or outdated settings across different development environments.

src directory

The src folder is the heart of the frontend’s codebase, encompassing all core logic and UI elements.

src / components

This directory houses reusable UI components, promoting modularity and a clean separation of concerns. Each component should have a clear responsibility (e.g., a form, a table, or a custom button), reducing duplication across the application. Well-structured, reusable components foster a consistent user experience and simplify maintenance by isolating visual and interactive logic.

src / contexthook

Contains use-context hooks for the application. A context hook taps into React’s Context API (via the useContext function) to access and subscribe to global or shared data, bypassing the need for excessive prop-drilling. This pattern keeps components cleaner and streamlines data flow. It is ideal for application-wide state (e.g., theme, user authentication status, or global settings) that multiple components may need. By centralizing data in a shared context, future scaling and refactoring become more straightforward.

src / controllers

In this context, controllers manage interactions between frontend data and any client-side logic or caching layers (often bridging requests to the backend). They interpret user actions (like button clicks or form submissions), fetch or modify data via services or APIs, and then pass updated information back to UI components. This promotes the single-responsibility principle, making it easier to test and maintain.

src / middleware

Middleware code here handles cross-cutting concerns, such as client-side request pre-processing, global error handling, or analytics event logging. The idea is to place shared logic that might be run before or after certain client-side tasks in one location, reducing duplication across multiple components or features.

src / pages

Page-level components define the route structure of the application, especially in a Next.js environment. Each file in this directory can correspond to a unique URL route. These pages often compose multiple smaller components and serve as entry points for more complex, page-specific logic. Keeping page components lean—delegating as much logic as possible to the controllers, services, or reusable components—improves maintainability.

src / services

This directory implements functions for interacting with Firebase and other external services or APIs. Services encapsulate the details of fetching and handling data, thereby allowing other parts of the frontend (e.g., controllers or components) to remain focused on application-specific logic. A well-organized services layer can drastically simplify maintenance and testing.

src / tests

This folder holds unit and integration tests that help ensure code reliability. Tests in this directory might cover component rendering, custom hooks, services, or pages. Keeping tests close to the relevant source code makes it easier to track and update them. Automated tests help catch regressions early, enabling teams to maintain consistent quality as the codebase grows.

src / utils

Helper functions and utilities that provide generic functionality—like date formatting, string manipulation, or other small, shareable snippets—belong here. By collecting them in one place, the application avoids duplicating logic and remains easier to extend.

Other Files in src root

public folder

A dedicated space for static assets such as HTML templates, images, fonts, and CSS. In Next.js, files placed here are served directly at the root of the implementing application’s URL (e.g., /images/logo.png). Keeping static files in public ensures that build processes and bundlers do not alter or transpile them, making it simpler to manage external resources.

Backend Folder

The backend folder stores all server-side logic, API routes, and Next.js server-side rendering capabilities. By relying on Next.js, you can implement server-rendered pages when needed (e.g., SEO-critical content or dynamic data fetching). This folder also integrates with PostgreSQL for data persistence, and may leverage Firebase for user authentication, logging, or configuration.

This setup allows teams to build a modern, server-side–capable React application (via Next.js) while still relying on a robust relational database (PostgreSQL). As a result, developers can handle tasks such as authentication, data retrieval, or server-side rendering in the backend, while the frontend focuses on presenting data and providing a seamless user experience.

config directory

Contains configuration files, potentially exported via Firebase Remote Config, for server settings. This includes database configuration (db-config.ts), Firebase Admin SDK details, and third-party integrations like LinkedIn. Storing these in a single place increases visibility and consistency, ensures secure handling of environment variables, and keeps sensitive credentials away from your codebase (for example, in environment variables or secure configuration services).

src directory

Houses the main application logic for the backend, mirroring the structure and rationale of the frontend src folder but with a focus on server-side needs.

src / controllers

Server-side controllers handle incoming requests, coordinate with data models in PostgreSQL, and deliver responses. They are a key link between client requests and backend logic, responsible for data validation, database queries, and returning data in a consumable format.

src / middleware

Shared logic that runs before or after certain server-side routes (or endpoints) resides here. This typically covers functionality like authentication checks, logging, input sanitization, error handling, and request parsing.

src / routes

Defines endpoints and server-side routes for your application. This directory is often used when you want to logically group and declare different API paths, especially if you have multiple modules or features requiring separate routes.

src / server

Acts as the main entry point to start the backend application. For Next.js, this might include custom server logic or advanced configurations. When run locally, it allows developers to test server-side features without having to deploy to a remote environment.

src / types

Defines TypeScript types for the backend, including request or response interfaces. Storing backend-specific types here keeps them cleanly separated from frontend interfaces, though you can have a shared folder if certain interfaces apply to both.

src / utils

Utility functions that perform generic tasks, such as error handling, data formatting, or HTTP request wrappers. As with the frontend’s utils folder, this ensures that common logic can be shared across multiple features without duplication.

Docs Folder

docs / product

Folder that stores product requirements documentation for new features that are being built or are to be built

docs / engineering

Folder that stores the engineering documentation for the product.

docs / public

Folder that stores any public documentation for the product that is kept in source code noting that most of this documentation is maintained in the product itself.

Testing and CI/CD

A dedicated section (or directory) focusing on testing strategy and continuous integration:

Strategy

In general CI/CD is rather straight forward. It encourages simplified gitflow with dev, and  main branches as long living, and feature branches as short living. For development environment and main correspondingly.
Main branch should be always last working revision of code, which is definitely working.
Also repo include tags in semver.org format to achieve simple and straightforward release versioning.

Branch naming

Generally branch naming follows this pattern <type>/descriptive-name

Git commit naming convention

Generally it’s advised to follow conventionalcommits.org when writing commit message. Though it’s mandatory only for code in main branch

Dev – main merging

It’s preferably to merge as often as you can (e.g. on per feature basis)  to achieve smooth process of integration of these two branches. Though it’s advised to merge them at least once a sprint.

Pull Requests

Pull requests MUST have relevant brief subject.

Pull requests SHOULD have a description that explains the changes made, important notices etc.

CI/CD Configuration

For now it’s assumed that CI/CD will have the following features:

Stuff We Clearly Need to Add

Security & Authentication

Elaborates on how user sign-up, login, and roles are handled across the stack:

Performance & Monitoring

A section describing performance optimization strategies and monitoring tools:

Internationalization & Accessibility (Optional)

If the application plans to support multiple locales or accessibility standards:

Accessibility: Testing and guidelines (e.g., ensuring compliance with WCAG standards).w

Get in touch
Company Resources
Compliance
Copyright
  • © 2025 One to One Hundred. All Rights Reserved.
  • Site by Arcbound.