Stakewolle Test Assignment

Referral system

Installation and Setup

1. Install Docker and Docker Compose if they are not already installed on your system.

2. Clone the project repository:

git clone https://github.com/Djama1GIT/stakewolle-test-assignment.git
cd stakewolle-test-assignment

3. Start the project:

docker-compose up --build

User Interface

After starting the project, you can access the Swagger user interface at: http://localhost:8080/docs.
In Swagger, you can view the available endpoints and their parameters, and also make requests to the API.

Usage Examples

1. Login:

curl -i -X POST -d \
  "grant_type=password&username=user@example.com&password=string&scope=&client_id=&client_secret=" \
  http://localhost:8080/auth/login

HTTP/1.1 204 No Content
date: Tue, 13 Feb 2024 23:20:09 GMT
server: uvicorn
set-cookie: fastapiusersauth=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiYXVkIjpbImZhc3RhcGktdXNlcnM6YXV0aCJdLCJleHAiOjE3MDc4NzAwMDl9.tt5DLy0MJOJWjgK4zsAfGIOkNlGQ3OjVuqyRkXltShQ; HttpOnly; Max-Age=3600; Path=/; SameSite=lax; Secure

2. Logout:

curl -i -X POST -H "Cookie: fastapiusersauth=your_jwt_token" \
http://localhost:8080/auth/logout

HTTP/1.1 204 No Content
date: Tue, 13 Feb 2024 23:21:42 GMT
server: uvicorn
set-cookie: fastapiusersauth=""; HttpOnly; Max-Age=0; Path=/; SameSite=lax; Secure

3. User registration:

curl -i -X POST -H "Content-Type: application/json" -d \
  '{
    "email": "user@example.com",
    "password": "string",
    "is_active": true,
    "is_superuser": false, 
    "is_verified": false
  }' http://localhost:8080/auth/register/\?referral_code=GADJIIAVOV

HTTP/1.1 200 OK
date: Tue, 13 Feb 2024 23:14:09 GMT
server: uvicorn
content-length: 199
content-type: application/json

{
  "id": 1,
  "email": "user@example.com",
  "is_active": true,
  "is_superuser": false,
  "is_verified": false,
  "referral_code": null,
  "referral_expiration": null,
  "referrer_id": null,
  "referrals": null,
  "referrer": null
}

4. Getting information about referrals by their ID:

curl -X GET http://localhost:8080/referrals/by_id/1

{
  "referrer": 1,
  "referrals": [
    115,
    116,
    117
  ]
}

5. Getting the referrer code by email:

curl -X GET http://localhost:8080/referrals/code_by_email/user@example.com

{
  "code": "GADJIIAVOV"
}

6. Creating a referrer code:

curl -X POST -H "Content-Type: application/json" \
  -H "Cookie: fastapiusersauth=your_jwt_token" \
  -d '{"code": "GADJIIAVOV", "expiration": "2024-02-24T12:00:00.000Z"}' \
  http://localhost:8080/referrals/create_code

{
  "code": "GADJIIAVOV",
  "expiration": "2024-02-24T12:00:00.000Z"
}

7. Deleting a referrer code:

curl -i -X DELETE -H "Cookie: fastapiusersauth=your_jwt_token" \
  http://localhost:8080/referrals/delete_code

HTTP/1.1 200 OK
date: Tue, 13 Feb 2024 23:37:48 GMT
server: uvicorn
content-length: 0

Validation Error

HTTP/1.1 422 Unprocessable Entity
date: Tue, 13 Feb 2024 23:49:59 GMT
server: uvicorn
content-length: 205
content-type: application/json

{
  "detail": "Registration at this email address is not available"
}

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": [
        "path",
        "code"
      ],
      "msg": "String should have at least 4 characters",
      "input": "G",
      "ctx": {
        "min_length": 4
      },
      "url": "https://errors.pydantic.dev/2.6/v/string_too_short"
    }
  ]
}

Internal Server Error

HTTP/1.1 500 Internal Server Error
date: Tue, 13 Feb 2024 23:48:58 GMT
server: uvicorn
content-length: 34
content-type: application/json

{
  "detail": "Internal Server Error"
}

Technologies Used

• Python - The programming language used for the project.
• REST - The architectural style for building distributed systems, used in the project to create the API.
• FastAPI - The Python framework used in the project to implement the REST API.
• Redis - An in-memory database used in the project for data caching and storing Celery tasks.
• PostgreSQL - A relational database used in the project for data storage.
• SQLAlchemy - An Object-Relational Mapping (ORM) used in the project for working with the database.
• Alembic - A database migration library used in the project to update the database structure when data models change.
• Docker - A platform used in the project for creating, deploying, and managing containers, allowing the application to run in an isolated environment.

Terms of Reference

A simple RESTful API service for a referral system needs to be developed.

Functional requirements:

• User registration and authentication (JWT, OAuth 2.0) ✅
• Authenticated users should be able to create or delete their referral code. Only 1 code can be active at a time ✅
• When creating a code, its expiration date must be set ✅
• Ability to retrieve a referral code by the referrer's email address ✅
• Ability to register as a referral using a referral code ✅
• Retrieve information about referrals based on the referrer's ID ✅
• UI documentation (Swagger, ReDoc) ✅

Optional tasks:

• Use clearbit.com/platform/enrichment to obtain additional user information during registration;❌
• Use emailhunter.co to verify the specified email address ✅
• Cache referral codes using in-memory database ✅
• Readme.md file with project description and instructions for deployment and testing ✅

Stack:

• Use any modern web framework ✅
• Use a relational database and migrations (Sqlite, PostgreSQL, MySQL) ✅
• Host the project on GitHub ✅

Project requirements:

• Code cleanliness and readability;
• All I/O bound operations should be asynchronous;
• The project should be well-structured;
• The project should be easy to deploy, handle non-standard situations, be resilient to incorrect user actions, etc.