Skip to content

Backend Guide

The backend is a robust Django application serving a GraphQL API (via Graphene). It uses a modular architecture to separate concerns (Auth, KPIs, Time Management).

Project Structure

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
backend/
├── PrimeBank/              # Project Configuration (settings, urls)
│   ├── PrimeBankApp/       # Main Application Scope
│   │   ├── migrations/     # Database migrations
│   │   ├── models.py       # Data Models (CustomUser, Team, TimeClock)
│   │   ├── schema_*.py     # Modular GraphQL Schemas
│   │   ├── views.py        # REST Views (if any)
│   │   └── admin.py        # Django Admin config
│   ├── settings.py         # Global Settings
│   └── urls.py             # Main Route definitions
│
├── manage.py               # Django CLI
├── pyproject.toml          # Dependencies (managed by uv)
└── Dockerfile              # Container definition

Development

Setting up Virtual Environment

We recommend using uv or standard venv.

1
2
uv sync
source .venv/bin/activate

1
2
3
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

1
2
3
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Database Migrations

1
2
uv run manage.py makemigrations
uv run manage.py migrate

1
2
python manage.py makemigrations
python manage.py migrate

1
2
python3 manage.py makemigrations
python3 manage.py migrate

Running the Server

Start the development server at http://localhost:8000:

1
uv run manage.py runserver

1
python manage.py runserver

1
python3 manage.py runserver

Data Models

We use a CustomUser model to handle specific business requirements (Teams, Roles).

PrimeBankApp/models.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
class CustomUser(AbstractUser):
    email = models.EmailField(unique=True)
    team = models.ForeignKey(
        Team,
        on_delete=models.SET_NULL,
        related_name="members",
        null=True,
    )
    is_admin = models.BooleanField(default=False)
    # ...
    USERNAME_FIELD = "email"

GraphQL Architecture

The schema is split into multiple modules for better maintainability.

  • schema.py: Main entry point aggregation
  • schema_auth.py: Authentication mutations
  • schema_time_clock.py: Clock-in/out logic
  • schema_kpi.py: Performance metrics

Example: Mutation Definition

Mutations are defined as Graphene classes and utilize Django Object Types.

PrimeBankApp/schema_time_clock.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
class ClockIn(graphene.Mutation):
    class Arguments:
        user_id = graphene.ID(required=True)

    time_clock = graphene.Field(TimeClockType)

    @classmethod
    def mutate(cls, root, info, user_id):
        # Business logic validation
        if TimeClock.objects.filter(user_id=user_id, day=day).exists():
             raise GraphQLError("This user already clocked in today.")

        # ... logic to create TimeClock

Testing

Run the test suite using pytest.

1
uv run pytest --cov=PrimeBankApp

1
2
python manage.py test
pytest

Authentication

The API uses JWT (JSON Web Tokens) via django-graphql-jwt.

  • Mutation: tokenAuth (Login)
  • Mutation: refreshToken (Keep session alive)
  • Header: Authorization: JWT <token>