Folder Structure

prisma/

This directory contains Prisma configuration and migration files, essentially serving as the mapping layer between the application and the database.

prisma/migrations

This folder contains database migration files generated by Prisma. note that prisma/migrations is auto-generated when migrations are run and that it should generally not be manually edited.

prisma/schema.prisma

This file defines the Prisma models which correspond to database tables. These models are then utilized for database operations via the Prisma Client.

src/

This is the root directory for all the application's source code, effectively separating it from other concerns like configuration, database scripts, and documentation.

src/api/

The API-related code lives here. For applications with other major components (e.g., a web frontend), those would exist in parallel folders at the same level as api/.

src/api/controllers/

Controllers receive HTTP requests, delegate tasks to services, and send back HTTP responses. They may contain request-handling logic but should generally be lean, deferring business logic to the services.

src/api/domain/

This folder hosts domain objects that encapsulate core business logic; they are typically used and manipulated in the src/api/services/ layer. For example, in an e-commerce app, a Cart could be a domain object that has methods like addProduct, removeProduct, or calculateTotal.

Domain objects can be simple (e.g., a Product object with attributes and behaviors) or more complex, involving various design patterns like factories, aggregates, or value objects.

src/api/models/

Models in this folder typically represent data structures or objects that don't fit neatly into the Prisma-generated models. These could include complex data types, objects that involve application-specific logic that doesn't belong in the database, or data models for APIs and services external to the application.

For example, if you're integrating with a third-party API, you might define a model that represents the data you'll receive from that API. This model could then be used to validate or manipulate that data before it's passed on to your domain objects or stored in your database.

In essence, while Prisma models are a direct mapping of your database schema, the models in this folder are supplementary and help to shape the data in ways specific to your application needs.

src/api/services/

Services act as a bridge between the outside world (HTTP requests, database operations) and your domain objects. They contain the reusable business logic that's not specific to any single entity or "thing" in your system. Services handle the "how" of your application's functionality, often orchestrating complex interactions between multiple domain objects, Prisma models, and even other services.

For example, a CheckoutService might use a Cart domain object and a User Prisma model to implement a checkout process. The service could validate that the cart and user meet certain conditions, apply discounts, calculate the total price, create an order in the database, and send an email to the customer.

In summary, services are more procedure-oriented and are responsible for implementing the actions that your application can perform, possibly involving multiple domain objects and data models to accomplish these tasks.

src/api/routes/

Route files define the API endpoints and wire up incoming requests to the appropriate controllers.

src/api/middlewares/

Middlewares act as a pipeline between the HTTP request and response. They can manipulate request and response objects, handle authentication, logging, etc.

src/api/validations/

This folder contains request validation logic. Libraries like Joi might be used to ensure that incoming data meets certain criteria before being processed.

src/config/

This folder holds configuration files, potentially defining environment variables, database settings, etc. Libraries like dotenv are commonly used to load these configurations into the application.

src/app.js

The entry point of the application resides here. This file is responsible for setting up the Express application, importing and using global middlewares, and tying all the components together.

index.js files

Each folder contains an index.js file which serves as a centralized export point for that folder's modules. This makes it easier to import them elsewhere in the application.

Understanding the Folder Structure

Starting Point (src/app.js)

app.js serves as the application's entry point. Here, the Express application is initialized, global middlewares are set up, and routes are imported.

API Flow

Route Handling (src/api/routes/): Routes determine which controller gets invoked based on incoming HTTP requests. Middlewares may be applied for specific routes.

Middlewares (src/api/middlewares/): These functions perform tasks like validation, authentication, and logging. They can pass control to the next middleware function or terminate the request-response cycle.

Request Validation (src/api/validations/): Validation occurs either in a middleware or before the controller logic is executed to ensure incoming data is correct.

Controller Logic (src/api/controllers/): Controllers are invoked after all middlewares and are responsible for invoking appropriate services and returning responses.

Inside the Controller:

Validation and Data Preparation: If further validation is needed or data from the request needs to be prepared or transformed, this happens first.

Invoke Service(s): The controller invokes one or more services to perform the business logic. The services may:

• Use domain objects for complex operations and rules that encapsulate core business logic (src/api/domain/).
• Interact with Prisma models for database CRUD operations (prisma/schema.prisma).
• Communicate with external APIs, using models defined in src/api/models/ to validate or shape the data.
• Receive Data from Service(s): The service returns data, which might be a direct response to be sent back, or might need further processing.

Finalize Response: The controller packages this data into an HTTP response, potentially transforming it or adding additional metadata. The response is then sent back to the client.

Core Logic

Services (src/api/services/): Services handle core business logic. They often interact with Prisma for database operations and manipulate domain objects.

Extra

Domain Objects (src/api/domain/): Domain objects contain core business logic and encapsulate rules that aren't necessarily tied to the database. They can be utilized by services.

Configurations (src/config/): Global settings and configurations are stored here and can be accessed throughout the application.

Module Export and Import

The index.js files help in bundling exports from each folder, simplifying the import statements in other parts of the application.