Skip to content

Backend Architecture

Overall project structure

├── .github/
│   └── ISSUE_TEMPLATE/
├── backend/ # Backend
│    ├── backend/  # Backend
│          └── settings.py
│    ├── ctj_api/  # Backend
│    ├── manage.py
│    ├── poetry.lock
│    └── pyproject.toml  # Backend
├── dev/
│    ├── django.dockerfile
│    ├── vite.Dockerfile
│    └── dev.env
├── frontend/
├── mkdocs/
├── stage/
│    ├── Dockerfile
│    └── stage.env
├── .dockerignore
├── .gitignore
├── CONTRIBUTING.md
├── docker-compose.yml
├── LICENSE
└── README.md

Backend folder structure

├── backend/
│   ├── templates/
│   └── <Django Project Files>
├── ctj_api/
│   ├── migrations/
│   ├── <Django App Files>
│   └── <RESTFramework Files>
├── frontend_dist/
│   └── <Vite build Files>
├── staticfiles/
│   └── <Django built Static Files>
├── .flake8
├── entrypoint.sh
├── manage.py
├── openapi-schema.yml
├── poetry.lock
├── pyproject.toml
└── startServer.sh

Backend Architecture

These diagrams show how data flows through the app: Frontend and Backend UML diagrams

Summary

Backend Tech Stack: Django, DjangoRESTFramework

The backend architecture consists of the Django backend/ project, and the ctj_api/ Django apps. The frontend_dist/ directory serves as our frontend build folder. More about the frontend/ directory as it relates our frontend architecture can be found in our guide on Frontend Architecture.

Overview of Directories and Files

  • backend/backend/: houses the core Django project files.
  • <Django Project Files>: More on the files in this directory can be found in Django's documentation.
  • <Django App>: currently we have two directories that are Django apps: backend/ and ctj_api/. Within these directories are the default <Django App Files> that are created with every app as well as <RESTFramework Files>.
  • <Django App Files>: These files make up a Django App. To know more about these apps, read the section about Django App Files.
  • <RESTFramework Files>: Currently consists of serializers.py and permissions.py. These files are additional files that support Django via the DjangoRestFramework library.
  • manage.py: Part of Django, this is the entry point file for starting the Django server. This file handles a lot of critical settings, so be sure to read up on it in Django's documentation.


Django Build files

  • frontend_dist/: The frontend React application's vite build files go in here. Django will use this to build the static frontend site to be served over whitenoise in stage/production.
  • staticfiles/: The static files django will serve to the client in stage/production. This folder is built when we run python manage.py collectstatic
  • openapi-schema.yml: Django REST Framework automatically generates this OpenAPI specification using our API code.


Dependency management

  • pyproject.toml: A Python file that contains all dependencies for a project. It is the Python + Poetry equivalent to Javascript's package.json.
  • poetry.lock: Poetry's dependency lock file. Equivalent to package-lock.json in JS.


Other files

  • .flake8: flake8 linter settings.
  • entrypoint.sh: script that docker uses to build and start the stage and prod environments.
  • startServer.sh: you can use this script to test and start the django server on your local machine without using docker.

Django App Files

├── migrations/
│   └── __init__.py
├── __init__.py
├── admin.py
├── apps.py
├── models.py
├── tests.py
├── urls.py
└── views.py

Files generated by Django when creating a new Django app

These files use DjangoRestFramework in order to quickly create an API. The most often edited files here are models.py, urls.py, and views.py. The models define the schema for our database tables. Once the models are made, they are routed to views.py where the data is transformed and exposed to our API. It is in views where we create handlers to manage REST operations.

Please refer to Django's documentation for more information.

Django REST Framework Files

The backend/ctj_api/ folder houses the core CivicTechJobs API server files.

├── permissions.py
├── serializers.py

RESTFramework files used to create a Django REST API

Serializers turn the data from the database into a Python-readable form.

Permissions allow you to create access permissions for specific API endpoints.

Please refer to DjangoRESTFramework's documentation for more information.

Linting the backend

Run before making a backend PR:

poetry run isort .
poetry run black .
poetry run flake8
  • Make sure you are in the /backend folder
  • Make sure you run it in the above order (isort, then black, then flake8)
  • isort: sorts the import statements
  • black: automatically formats python code
  • flake8: lints python code

Additional Resources

Django Documentation
DjangoRestFramework Documentation
OpenAPI Documentation
Poetry Documentation
Feature/lint python redo by LoTerence · Pull Request #603 · hackforla/CivicTechJobs · GitHub