Skip to content

Understanding Our Monorepo Project Structure

Welcome to the project! You are entering a modern and organized development environment that uses a monorepo structure with multiple services. Don't worry about understanding everything at once. This document is a practical guide to help you get familiar with the architecture and know where to find what you need. Many of the techniques and patterns will be learned on a day-to-day basis.

1. Monorepo Overview

Our project is a monorepo, which means that all the source code (frontend, backend, gateway) lives in a single repository. This facilitates collaboration and consistency across the different modules.

It is composed of:

  • 1 Frontend: Built with Next.js (React).
  • 5 Backend Microservices:
    • 3 in Java: Using Spring Boot.
    • 1 in Python: Using FastAPI and Peewee.
    • 1 Gateway in Node.js: Using Express and an Nginx as a reverse proxy.

2. Folder and Component Structure

Let's dive into the folder organization so you know where to find each part of the project.

2.1. frontend/ (Next.js)

This is where the entire web application that end-users interact with resides.

  • src/: Contains the main Next.js source code.
    • app/: The routes for Next.js.
      • (private)/: Pages that require authentication for access (e.g., feedback/, userlist/).
      • (public)/: Publicly accessible pages (e.g., login/, setpassword/).
    • components/: Reusable React components used across various pages (e.g., NavBar/).
    • dtos/: Data models (Data Transfer Objects) that define the structure of information exchanged with the backend.
    • services/: Functions for making API calls to the backend. This is where you will configure how the frontend "talks" to the microservices.
    • utils/: General utility functions.
    • __tests__/: Folder for the frontend application's tests.
  • Configuration Files: package.json, next.config.ts, tsconfig.json, Dockerfile, etc., are configuration files for the Next.js project and its execution environment.

2.2. java_backend/ (Spring Boot)

This folder groups the three Java microservices.

  • libs/: Contains shared libraries among the Java microservices.
    • security/: A custom security library (JWT) that is reused by the other microservices. This is where the logic for handling authentication tokens is located.
  • microservices/: Each subfolder here is an independent Java microservice:
    • feedbackrequest/: Responsible for managing feedback requests.
    • feedbackresponse/: Handles feedback responses.
    • usermanagement/: Manages users (collaborators, PDMs, administrators).
  • Inside each Java microservice, you will find the following practical structure (following simplified DDD layers):
    • controller/: Receives HTTP requests from the frontend (or the gateway), validates the input, and calls the service layer.
    • service/: Contains the main business logic. This is where you will implement the rules of how things work in our domain. It uses repositorys to interact with data.
    • entity/: Represents the domain entities, i.e., objects that have a unique identity and are persisted in the database (e.g., User, FeedbackRequest).
    • repository/: Interfaces that define how the service will save, retrieve, or update entitys in the database. It abstracts the details of how communication with the database works.
    • dto/: Classes for Data Transfer Objects (DTOs), used to receive data from requests and send data in responses, facilitating communication between layers.
    • exceptions/: Classes for handling application-specific errors.
    • configuration/: Microservice-specific configurations (e.g., security, database).
  • pom.xml: Maven configuration files for each microservice and for the java_backend module as a whole, defining dependencies.
  • Dockerfile: Files for building the Docker images of the microservices.

2.3. python_backend/ (FastAPI)

Here is the Python microservice, which likely handles the visualization of feedback responses.

  • feedbackresponseview/: The root directory of the microservice.
    • app/: Contains the source code of the FastAPI application.
      • routes/: Where you will define the API endpoints (equivalent to controllers in Java).
      • services/: Contains the business logic (similar to the service layer in Java).
      • models/: Represents the entities and data models for Peewee (equivalent to entity and dto in Java, but for Python/ORM).
      • repositories/: Where the logic for interacting with the database using Peewee will be (similar to the repository layer in Java).
      • config/: Application configurations, such as database connection.
      • auth/, exceptions/, middleware/: Other folders for organizing authentication, error handling, and middleware functionalities.
    • tests/: Folder for unit and integration tests of the Python microservice.
    • pyproject.toml: Project configuration and dependency file (similar to pom.xml or package.json).
  • Dockerfile: File for building the Docker image of the Python microservice.

2.4. node_backend/ (Express Gateway)

This is our API Gateway, built with Node.js and Express.

  • api_gateway/: The gateway's directory.
    • src/: Contains the gateway's code.
      • app.ts, index.ts: Main files where the routing and proxy logic for the microservices is defined.
      • app.spec.ts: Tests for the gateway.
  • package.json, tsconfig.json: Configuration files for the Node.js project.
  • Dockerfile: File for building the gateway's Docker image.

2.5. gateway/ (Nginx)

This folder contains the Nginx configuration file, which acts as a reverse proxy to direct requests to the Node.js Gateway and, subsequently, to the correct microservices.

  • nginx.conf: The main Nginx configuration file.

3. Essential Tools and Patterns

Our project follows some conventions and uses specific tools:

  • Monorepo: Everything in the same place.
  • Docker and Docker Compose: We use these to standardize the development and production environments. You will find docker-compose-dev.yml (for development) and docker-compose.yml (for production) in the root directory.
  • Layered Structure (Controller, Service, Entity/Model, Repository): This is the main organization of each backend microservice to separate responsibilities.
    • Controller: Handles API input and output (HTTP).
    • Service: Contains the business logic.
    • Entity/Model: Represents the data and its behavior.
    • Repository: Abstracts communication with the database.
  • JWT (JSON Web Tokens): For user authentication, ensuring that only authorized people can access certain features.
  • Bitbucket Pipelines: For CI/CD (continuous integration and delivery) automation, configured in bitbucket-pipelines.yml.

4. Next Steps and Where to Find Help

Don't feel overwhelmed! The beauty of the monorepo and the layered organization is that you can focus on one part at a time.

  • To Get Started: Concentrate on the tasks assigned to you. Understand the controller, service, and repository of that specific microservice.
  • Documentation: We have extensive internal documentation. Don't hesitate to consult it or ask your Tech Lead Tutor or a teammate. They are here to help!
  • Learn on a Day-to-Day Basis: Many of the techniques and patterns (like DDD, JWT, and the details of each framework) will be understood as you develop features. It is not necessary to master everything before you start.

You are ready to embark on this journey. Which part of the application are you most curious to explore first?