# Organization of code

#### Overview

This repository is structured as a single, modern web application with a strong focus on modularity and clarity. Each part of the codebase has a clear responsibility, making it easier for contributors to navigate, understand, and extend the project without needing deep context upfront.

Instead of splitting functionality across multiple packages, we keep related concerns close together and rely on conventions to keep things predictable.

***

#### Top-level structure

At the root of the repository, you will find configuration, documentation, and project-level setup alongside the application code.

* [**app/**](https://github.com/betterbugs/dev-tools/tree/main/app)\
  Contains the main application code. This is where most feature and UI-related development happens.
* [**public/**](https://github.com/betterbugs/dev-tools/tree/main/public)\
  Static assets such as images, icons, and metadata used by the application.
* **.**[**github/**](https://github.com/betterbugs/dev-tools/tree/main/.github)\
  GitHub-specific configuration including workflows, issue templates, and automation.
* **docs and meta files**\
  Files such as [`README.md`](https://github.com/betterbugs/dev-tools/blob/main/README.md), [`CONTRIBUTING.md`](https://github.com/betterbugs/dev-tools/blob/main/CONTRIBUTING.md), [`SECURITY.md`](https://github.com/betterbugs/dev-tools/blob/main/SECURITY.md), and [`CHANGELOG.md`](https://github.com/betterbugs/dev-tools/blob/main/CHANGELOG.md) describe how the project works, how to contribute, and how releases are managed.
* **Configuration files**\
  Files like `next.config.js`, `tsconfig.json`, `tailwind.config.ts`, and release configuration define how the project is built, styled, and released.

***

#### Inside the app directory

The `app` directory follows a structure that aligns with Next.js App Router conventions while keeping feature code organized and reusable.

Common areas you will interact with include:

* **app/\[slug]/**\
  Dynamic routes used to render individual tools or features based on the URL.
* **app/components/**\
  Reusable React components used across the application.\
  This includes feature-specific components as well as shared UI building blocks.
* **app/layout and page files**\
  Application entry points, layouts, and top-level pages.
* **app/contexts/**\
  React context providers used for shared state across multiple components.
* **app/libs/**\
  Shared utilities, constants, helpers, and configuration objects used throughout the codebase.
* **app/styles/**\
  Global styles and styling-related configuration.

***

#### Why this structure

This organization is intentional and optimized for:

* Easy onboarding for new contributors
* Clear separation of concerns
* Predictable locations for new code
* Minimal duplication across features

When adding new functionality, following this structure helps keep the codebase consistent and maintainable over time.

***

#### Where to start as a contributor

If you are new to the project:

* Start by exploring the `app` directory
* Look at existing components and utilities before adding new ones
* Use the `libs` directory for shared logic instead of duplicating code
* Keep feature-specific logic close to where it is used
* Ready to contribute? Learn the steps [here](https://docs.betterbugs.io/contributing-to-betterbugs/how-to-contribute)

If something does not clearly fit into the existing structure, chat with us on discord or open an issue and start a discussion. We value clarity over assumptions.