=======
General
=======

Stack
-----------

- **Main Components**
   - **Backend Framework**:
      - `Django`: The primary framework that powers the application.
   - **Database Management Systems**:
      - `PostgreSQL`: The primary relational database system for storing application data.
      - `Redis`: In-memory database system used for caching, session management, and other supportive tasks.
   - **API and Real-time Functionality**:
      - `Django Rest Framework`: A powerful toolkit for building RESTful APIs.
      - `Channels`: Enables Django to handle WebSockets, HTTP2, and other asynchronous protocols.
   - **Asynchronous Processing**:
      - `Celery`: A distributed task queue for executing tasks asynchronously.

- **Development and Documentation Tools**
   - **Code Quality and Validation**:
      - `Pre-commit`: A tool to ensure that code changes meet the required standards before they're committed.
      - `mypy`: A static type checker for Python, ensuring better code type safety.
   - **Testing**:
      - `factory-boy`: A flexible and usable test fixtures replacement. Helps in creating data factories for tests.
      - `faker`: A tool for generating fake data for tests.
      - `coverage`: Analyzes the code to determine the coverage of project tests.
   - **Documentation**:
      - `sphinx`: A tool that makes it easy to create intelligent and beautiful technical documentation.
      - `drf-yasg`: A tool for render OpenAPI specification for Django Rest Framework.

Project initialization
-------------------------

- **Code Quality and Validation Tools**:
  - `pre-commit install`: Initializes pre-commit hooks for the repository.
  - `mypy core`: Runs MyPy to check the codebase for type consistency.
  - `rm -rf .mypy_cache/`: Clears the MyPy cache. Useful when encountering caching issues with MyPy.

Structure of the Project
-------------------------

  - **api**: This directory encompasses everything tied to the project's REST API endpoints. This includes, but is not limited to: *views, serializers, URLs, filters, and permissions*.

  - **apps**: A centralized location for everything related to database structures and administrative tasks. You'll find: *models, admin configurations, and constants* here.

  - **common**: A utility directory containing shared resources like tools, constants, and other elements that might find use across various project components.

  - **consumers**: All things related to Channels consumers reside here, facilitating the handling of WebSockets and other asynchronous protocols.

  - **docs**: This directory houses the project's technical documentation, including Sphinx configurations and documentation files.

  - **services**: A dedicated directory for business logic components. It's where you'll find methods and functions tied to the application's core functionalities.

  - **tasks**: Here you'll find all asynchronous tasks, usually managed by tools like Celery.

  - **tests**: As the name suggests, this directory contains test suites, test cases, and other testing utilities to ensure the robustness and reliability of the project.

User Access and Permissions Guide
---------------------------------


There are two main interfaces for users to interact with - the Admin Interface and the API.

1. **Admin Interface**: `admin/ </admin/>`
    - **Purpose**: This interface is like a control panel. It lets certain users view, add, edit, or delete records in our database.
    - **Access Control**: Only users with special privileges (superusers) can access this.
    - **Login Mechanism**: We use a straightforward login method, provided by Django, where you enter your username and password.
    - **Interface**: It comes with a user-friendly web interface to navigate and make changes.

2. **API Interface**: `api/ </api/>`
    - **Purpose**: This is a digital communication channel that software applications use to communicate. It's like a set of coded instructions.
    - **Login Mechanism**: Here, we use something called a JWT token. Think of it as a digital key that proves your identity.
        - `/api/token/` - This is like a key-making machine. You provide your login credentials, and it gives you two digital keys - an *access key* and a *refresh key*.
        - `/api/token/refresh/` - If your access key gets old and rusty, you can use your refresh key here to get a shiny new access key.
        - Once you have an access key, you should include it as a 'Bearer token' every time you send a request to access the protected parts of the API.
    - **Activation**: Before using your account here, you need to activate it. This is an added layer of security. You'll get an activation link in your email, or an admin can do it for you.

View Class Additional Parameters
---------------------------------

There are a few special attributes added to the view classes to enhance and customize their documentation and behavior in the API. This section describes these attributes.

- **tags**:
    - **Purpose**: Determines the section in which the API documentation for this view will appear.
    - **Typically**: Corresponds to the app the view belongs to.
    - **Usage**:

      .. code-block:: python

          class SomeView(APIView):
              tags = ['Some App']

- **subtag**:
    - **Purpose**: Specifies a label at the beginning of the `operation_id` to indicate which feature the endpoint relates to.
    - **Usage**:

      .. code-block:: python

          class SomeFeatureView(APIView):
              subtag = 'SomeFeature'

- **model_name**:
    - **Purpose**: Allows you to replace the default name of the model with a custom name in the representation.
    - **Usage**:

      .. code-block:: python

          class CustomModelNameView(ModelViewSet):
              model_name = 'CustomName'


Pre-commit Hooks
----------------

This section provides a brief overview of the `pre-commit` hooks used in the project.

1. **pre-commit/pre-commit-hooks**
   - **Hooks:**
      - `trailing-whitespace`: Removes any trailing whitespace.
      - `end-of-file-fixer`: Ensures that a file is either empty or ends with one newline.
      - `check-yaml`: Checks yaml files for parseable syntax.
      - `detect-private-key`: Checks for the existence of private keys.
      - `check-case-conflict`: Checks for files with names that would conflict on a case-insensitive filesystem like macOS or Windows.
      - `check-merge-conflict`: Checks for files that contain merge conflict strings.

2. **PyCQA/isort** – Sorts your imports automatically. Excludes migrations.

3. **myint/autoflake** – Removes unused imports and unused variables from Python code.

4. **psf/black** – The uncompromising Python code formatter.

5. **pre-commit/mirrors-mypy** – A static type checker for Python.

6. **dhruvmanila/remove-print-statements** – Removes any print statements. This is helpful in ensuring debug print statements don't get committed.

7. **pycqa/flake8** – A tool to enforce coding style rules. It checks your code against certain rules, and can be extended with additional plugins.

8. **adamchainz/django-upgrade** – Automatically upgrades Django version-specific code for newer versions.

9. **local**
   - **Hooks:**
      - `run-django-tests`: Runs Django tests.
      - `check-test-coverage`: Runs tests and checks the coverage.

.. note::

      Each of these hooks plays a crucial role in maintaining the quality and consistency of the codebase. Ensure to run them before committing changes.