diff --git a/services/ads/README.md b/services/ads/README.md new file mode 100644 index 00000000..4dd0d001 --- /dev/null +++ b/services/ads/README.md @@ -0,0 +1,137 @@ +# Advertisements Service + +## Description + +This service is responsible for managing the banner advertisements served to the frontend service of the application. There are two variations of this service, one uses Python and the other uses Java. + +## Python service + +The Python service is a Flask application that uses SQLAlchemy to connect to a PostgreSQL database. The service is packaged as a Docker image and typically used in a Docker Compose file (see the root of this repo). + +### Datadog configuration + +#### Logs + +Logging is configured in the `docker-compose.yml` file along with the Datadog Agent. + +#### APM + +The `ddtrace` library is used to instrument the Python service. The `ddtrace` library is installed in the `requirements.txt` file. The `ddtrace-run` command is used to run the service in the `Dockerfile`. + +Log injection is enabled in the `docker-compose.yml` file, but the logs are formatted in the `ads.py` file. + +### Endpoints (Python) + +Use the following endpoints to interact with the service. + +#### GET / + +Returns a message indicating that the service is running. + +##### Request + +```text +GET / +``` + +##### Response + +```text +Hello from Advertisements! +``` + +#### GET /ads + +Returns a list of all advertisements. There are only three advertisements in the database. + +##### Request + +```text +GET /ads +``` + +##### Response + +```json +[ + { + "id": 1, + "name": "Discount Clothing", + "path": "1.jpg", + "url": "/t/clothing", + "weight": 15.1 + }, + { + "id": 2, + "name": "Cool Hats", + "path": "2.jpg", + "url": "/products/datadog-ringer-t-shirt", + "weight": 300.1 + }, + { + "id": 3, + "name": "Nice Bags", + "path": "3.jpg", + "url": "/t/bags", + "weight": 5242.1 + } +] +``` + +#### GET /banners/ + +Returns the banner image specified by the path parameter. Use this to display images on the frontend. + +##### Request + +```text +GET /banners/1.jpg +``` + +##### Response Type + +```text +image/jpg +``` + +#### POST /ads + +Creates a new advertisement with a random name and value. Currently doesn't work as intended (I believe). + +##### Request + +```text +POST /ads +``` + +##### Response + +```json +{ + "id": 4, + "name": "New Ad", + "path": "4.jpg", + "url": "/t/new", + "weight": 0.0 +} +``` + +### Database + +The Python service uses a PostgreSQL database. The database is configured in the `docker-compose.yml` file. + +The application uses SQLAlchemy to connect to the database. The `models.py` file contains the SQLAlchemy model and the `bootstrap.py` file contains database connection and setup code. + +#### Database schema + +The `ads` table has the following schema: + +| Column | Type | Description | +| --- | --- | --- | +| id | integer | Unique identifier for the advertisement (Primary Key) | +| name | string | Name of the advertisement | +| url | string | URL to redirect to when the advertisement is clicked | +| weight | float | Weight of the advertisement (used for A/B testing) | +| path | string | Path to the advertisement image | + + diff --git a/services/auth/README.md b/services/auth/README.md new file mode 100644 index 00000000..5e34b3b6 --- /dev/null +++ b/services/auth/README.md @@ -0,0 +1,4 @@ +# Authentication service + +## Description + diff --git a/services/backend/README.md b/services/backend/README.md new file mode 100644 index 00000000..56a192bb --- /dev/null +++ b/services/backend/README.md @@ -0,0 +1,6 @@ +# Backend service (product management) + +## Overview + +This service manages the products in the store. It is a Ruby on Rails application built using the Spree framework. The service is packaged as a Docker image and typically used in a Docker Compose file (see the root of this repo). + diff --git a/services/dbm/README.md b/services/dbm/README.md new file mode 100644 index 00000000..caf0d5b7 --- /dev/null +++ b/services/dbm/README.md @@ -0,0 +1,34 @@ +# DBM service + +## Description + +This service is used for our database monitoring courses, built with Python that uses the SQLAlchemy ORM to connect to a Postgres database. When the service is started, the library Faker is used to generate fake data for the database and in our labs we run a few queries in the background to simulate a load on the database. + +> TODO: Add queries from labs to this repo + +There is also a user-facing component to this service, which can be seen in the `frontend` service with a specific flag thrown in the `featureFlags.config.json` file. Turning it on will result in a product ticker being displayed in the navbar of the application. + +## Database schema + +The database schema can be found in the `models.py` file with these models: + +### items + +| Column | Type | Description | +| --- | --- | --- | +| id | Integer | Primary key | +| description | String | Description of the item | +| order_count | String | Number of times the item has been ordered | +| last_hour_order_count | String | Number of times the item has been ordered in the last hour | +| image_url | String | URL to an image of the item | + +### preorder_items + +| Column | Type | Description | +| --- | --- | --- | +| id | Integer | Primary key | +| description | String | Description of the item | +| order_count | String | Number of times the item has been ordered | +| last_hour | String | Number of times the item has been ordered in the last hour | +| image_url | String | URL to an image of the item | +| is_preorder | Boolean | Whether or not the item is a preorder item | \ No newline at end of file diff --git a/services/discounts/README.md b/services/discounts/README.md index 57676920..8acac302 100644 --- a/services/discounts/README.md +++ b/services/discounts/README.md @@ -1,3 +1,154 @@ -To test the words module: +# Discounts service -`python3 -m unittest test.py` +## Description + +This service is responsible for managing discounts written in Python using the Flask framework. It uses a PostgreSQL database to store the discounts. + +## Datadog configuration + +### Logs + +Logging is configured in the `docker-compose.yml` file along with the Datadog Agent. + +### APM + +The `ddtrace` library is used to instrument the Python service. The `ddtrace` library is installed in the `requirements.txt` file. The `ddtrace-run` command is used to run the service in the `Dockerfile`. + +Log injection is enabled in the `docker-compose.yml` file, but the logs are formatted in the `ads.py` file. + +## Endpoints + +Use the following endpoints to interact with the service. + +### GET / (health check) + +Returns a message indicating that the service is up and running. + +#### Request + +```text +GET / +``` + +#### Response + +```text +Hello from Discounts! +``` + +### GET /discount + +Returns a list of all discounts. + +#### Request + +```text +GET /discount +``` + +#### Response + +```json +[ + { + "id": 1, + "name": "10% off", + "description": "10% off all items", + "active": true + }, + { + "id": 2, + "name": "20% off", + "description": "20% off all items", + "active": true + }, + { + "id": 3, + "name": "30% off", + "description": "30% off all items", + "active": true + }, + ... +] +``` + +### POST /discount + +Creates a new discount at random. It doesn't accept a request body. + +#### Request + +```text +POST /discount +``` + +#### Response + +Returns all discounts with new one appended. + +```json +[ + { + "id": 1, + "name": "10% off", + "description": "10% off all items", + "active": true + }, + { + "id": 2, + "name": "20% off", + "description": "20% off all items", + "active": true + }, + { + "id": 3, + "name": "30% off", + "description": "30% off all items", + "active": true + }, + ... + { + "id": 99, + "name": "100% off", + "description": "New Discount", + "active": true + } +] +``` + +## Database + +The service uses a PostgreSQL database to store the discounts. The database is configured in the `docker-compose.yml` file. + +The application uses the SQLAlchemy ORM to interact with the database. The `Discount` and `Influencer` model are defined in the `models.py` file and the `discounts` table is created in the `bootstrap.py` file. + +### Schema + +The `discounts` table has the following schema: + +| Column | Type | Description | +| --- | --- | --- | +| id | integer | Unique identifier for the discount (Primary Key) | +| name | string | Name of the discount | +| code | string | Discount code | +| value | integer | Discount value | +| discount_type_id | integer | Foreign key to the discount type | + +> **Note**: We use these values the most. The other two tables seem serve a legacy purpose. + +The `discount_types` table has the following schema: + +| Column | Type | Description | +| --- | --- | --- | +| id | integer | Unique identifier for the discount type (Primary Key) | +| name | string | Name of the discount type | +| influencer_id | integer | Foreign key to the influencer | +| discount_query | string | Query to get the discount | + +The `influencers` table has the following schema: + +| Column | Type | Description | +| --- | --- | --- | +| id | integer | Unique identifier for the influencer (Primary Key) | +| name | string | Name of the influencer | +| discount_types | string | Discount types associated with the influencer | \ No newline at end of file diff --git a/services/frontend/README.md b/services/frontend/README.md new file mode 100644 index 00000000..9bf91b1f --- /dev/null +++ b/services/frontend/README.md @@ -0,0 +1,120 @@ +# Frontend service + +## Description + +The frontend services is a JavaScript application that uses the Next.js React framework. It includes it's own set of API routes, which are used to fetch data from the backend services. + +The service is based off of the [Next.js commerce template](https://github.com/vercel/commerce/tree/v1) and uses the Spree framework package to communicate with the backend service. + +## Datadog configuration + +### RUM + +**Configuration** +The frontend service is configured to use the [Datadog RUM](https://docs.datadoghq.com/real_user_monitoring/) agent. The agent is configured in the `_app.tsx` file. + +TODO: Update RUM version in repo and add otel (https://docs.datadoghq.com/real_user_monitoring/connect_rum_and_traces/?tab=browserrum#opentelemetry-support) + +**Global Context** +Every session to the application randomly selects a user from a list of users in the `/site/config/user_data.json` file to enrich RUM session data with user information. + +TODO: Add custom actions to repo + +### Logs + +TODO: Configure logging in API routes (add to repo) + +### APM + +TODO: Configure APM in API routes (add to repo from working lab example) + +## Code structure + +### packages + +The `packages` directory contains Node modules for different ecommerce solutions. This is remnant of the original template we used to build the service. The `spree` package is the only one that is used. + +TODO: Remove unused packages and move `spree` package into main application + +### site + +This is the main application directory, which is written . It contains the following directories: + +- `assets` - Contains some base theme stylesheet assets. (TODO: assess if we need to keep this directory or roll it into other directories (or remove entirely)) + +- `components` - This is the main directory for React components. It contains the following subdirectories: + + - `auth` - Contains components related to authentication, such as the login form. + + - `cart` - Contains components related to the cart that opens in the site's sidebar. This includes the cart itself, the cart item, and the cart's sidebar container. + + Styles are located in the `*.module.css` files. + + - `checkout` - Contains components related to the checkout process. This includes the checkout form, shipping view, the checkout page, and the checkout success page. + + It also includes a React context provider for the checkout process, which is used to store the current checkout state and share it among the components. + + - `common` - Contains components that are used throughout the application. This includes the application's header, footer, the main layout, among others. + + Noteable components include the `Ad` and `Discount` components that make requests to those respective services. + + - `icons` - Contains SVG icons that are used throughout the application. + + - `product` - Contains components related to different product views. This includes the product card, product list, product view, among others. + + - `ui` - Contains components that are used to build the application's UI. This includes the `Button`, `Input`, `Select`, among others. + + These components do not contain any business logic and are used to build other components. + + - `wishlist` - Contains components related to the wishlist. + +- `config` - Contains configuration files for the application. This includes the `user_data.json` file, which contains a list of users that are randomly selected to enrich RUM session data. + +- `lib` - Contains utility functions that are used throughout the application. + +- `pages` - Contains the application's pages. This includes the `api` directory, which contains the API routes that are used to fetch data from the backend services. + + Each page defined here maps to a route in the application. For example, the `pages/index.tsx` file maps to the `/` route. + +- `public` - Contains static assets that are served by the application. This includes the `favicon.ico` file, which is the application's favicon. + +- root-level files: + + - `.env.local` - Contains environment variables that are used by the application. Next.js requires that environment variables be prefixed with `NEXT_PUBLIC_` in order to be used in the browser. This file is not committed to the repository. + + - `.eslintrc` - Contains ESLint configuration for the application. + + - `.gitignore` - Files to ignore when committing code to the repository. + + - `.prettierignore` - Files to ignore when formatting code with Prettier. + + - `.prettierrc` - Prettier configuration. + + - `commerce-config.js` - Configures the application's connection to the backend service. (TODO: assess if we need to keep this file or roll it into other files) + + - `featureFlags.config.json` - Contains feature flags that are used by the application. + + - `global.d.ts` - Contains global type definitions for the application. + + - `next-env.d.ts` - Contains type definitions for Next.js. + + - `next.config.js` - Contains configuration for Next.js. + + - `package.json` - Node package configuration for the application. + + - `postcss.config.js` - Contains configuration for PostCSS. + + - `tailwind.config.js` - Contains configuration for Tailwind CSS. + + - `tsconfig.json` - Contains TypeScript configuration for the application. + +### root-level files + +> TODO: Consider removing the monorepo configuration when moving Spree package into main application, as we won't need it anymore. The end result should be the contents of `site` directory taking over this directory. + +- `.prettierignore` - Files to ignore when formatting code with Prettier +- `.prettierrc` - Prettier configuration +- `Dockerfile` - Dockerfile for building the application (TODO: create variation for built app) +- `package.json` - Node package configuration for the monorepo +- `turbo.json` - The Turbo configuration file for monorepo management +