Project Structure

These are the directories and files in the project. Parts are summarized for clarity.

Top level

/
├── app/     # (1)!
├── docs/    # (2)!
├── scripts/ # (3)!
├── docker-compose.yml # (4)!
└── pyproject.toml # (5)!

1. The django project. This is also what goes into the Docker image when it's generated by ./scripts/buildrun.sh. See Django Project below for details.
2. Documentation for the project code. See Documentation below for details.
3. Scripts used in the project. These are run in the commandline to do various project tasks. See Convenience Scripts for details.
4. The docker compose file.
5. The pyproject.toml file. This holds settings for project tools right now. We may combine this with app/setup.cfg in the future. We may move this file into app/ if it makes sense.

Django project

app/
├── core/ # (1)!
├── data/ # (2)!
├── peopledepot/ # (3)!
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── scripts/ # (4)!
│   └── convert.py
├── Dockerfile # (5)!
├── entrypoint.sh # (6)!
├── manage.py # (7)!
├── requirements.in # (8)!
├── requirements.txt # (9)!
└── setup.cfg # (10)!

1. The core app in django. This app contains the API and models. See Core App below for details.
2. The data app in django. This app contains the initial data migrations. See Data App below for details.
3. The django project configuration.
4. Scripts used in the project. This currently contains the convert.py script, which converts csv files into django initial data code. It's used to generate code for the initial data migrations.
5. Dockerfile used to build the Docker image.
6. Entrypoint script called by the Docker image.
7. Django manage.py script. In nearly all cases, there's no good reason to change this. Just leave it alone.
8. Requirements.in file used by uv pip compile. See the uv tool for details.
9. Requirements.txt file generated by uv pip install. Do not modify this file. Edit the requirements.in file instead. See the uv tool for details.
10. Config file for development support tools such as flake8 and pytest. flake8 is the only tool that doesn't support pyproject.toml yet, which is why we have this file.

Core App

core/
├── admin.py # (1)!
├── api/
│   ├── permissions.py # (2)!
│   ├── serializers.py # (3)!
│   ├── urls.py # (4)!
│   └── views.py # (5)!
├── apps.py # (6)!
├── initial_data/
│   ├── ...
│   └── Initial data in json or csv format # (7)!
├── migrations/
│   ├── nnnn_migration_name.py # (8)!
│   ├── ...
│   └── max_migration.txt # (9)!
├── models.py # (10)!
├── scripts/ # (11)!
├── tests/
│   ├── conftest.py # (12)!
│   ├── test_api.py # (13)!
│   ├── test_models.py # (14)!
│   └── test_permissions.py # (15)!
└── utils/ # (16)!
.   └── jwt.py # (17)!

1. Admin site configuration.
2. Permission classes definitions.
3. Serializers to control what data is sent to the client.
4. Routes for the API.
5. Views to retrieve data for the API.
6. AppConfig for the core app.
7. Initial data scripts. See Create initial data scripts for how to create these.
8. Migration scripts. These are generated by the makemigrations command.
9. File used by django-linear-migrations. It stores the last migration name for the app for use in git merge conflicts.
10. Models for the core app.
11. Scripts for the core app. We use it to hold temporary scripts in Create initial data migrations, but there's no need to commit them into git.
12. Test fixtures file
13. Test for the API
14. Test for the models
15. Test for the permissions
16. Utility scripts for the core app
17. Utility functions supporting JWT with Cognito

Data App

data/
└── migrations/
.   ├── nnnn_migration_name.py # (1)!
.   ├── ...
.   └── max_migration.txt # (2)!

1. Migration scripts. See Create initial data migrations for how to create these.
2. File used by django-linear-migrations. It stores the last migration name for the app for use in git merge conflicts.

Documentation

/
├── docs/
│   ├── [topics]/ # (1)!
│   ├── CONTRIBUTING.md # (2)!
│   ├── index.md # (3)!
│   ├── LICENSE # (4)!
│   ├── license.md # (5)!
│   └── _static/
├── CONTRIBUTING.md # (6)!
├── LICENSE # (7)!
├── mkdocs.yml # (8)!
└── README.md # (9)!

1. Directories containing markdown files on different topics.
2. Placeholder for the CONTRIBUTING.md file in the project root. MkDocs requires all documentation files to be in the docs/ directory. This file uses a snippet to import the source content.
3. Home page of the documentation site. This files uses a snippet to import the README.md file from the project root.
4. Placeholder LICENSE file. This file uses a snippet to import the LICENSE file from the project root. This is used for linking from the Documentation Homepage as well as the README.md file in the Github web interface, which knows the file by this name only.
5. Placeholder license.md file. This file uses a snippet to import the LICENSE file from the project root. This is used for the MkDocs nav section, which requires the md file extension.
6. Contributing file for the project. This name is capitalized according to Github conventions.
7. Licence file for the project. This name is capitalized according to Github conventions.
8. MkDocs config file.
9. README file for the project. This name is capitalized according to Github conventions.