docs: project structure

docs/architecture/project_structure.md

@@ -0,0 +1,139 @@
+# Project Structure
+
+These are the directories and files in the project. Parts are summarized for clarity.
+
+## Top level
+
+```bash
+/
+├── 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](#django-project) below for details.
+1. Documentation for the project code. See [Documentation](#documentation) below for details.
+1. Scripts used in the project. These are run in the commandline to do various project tasks. See [Convenience Scripts](scripts.md) for details.
+1. The docker compose file.
+1. 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
+
+```bash
+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](#core-app) below for details.
+1. The data app in django. This app contains the initial data migrations. See [Data App](#data-app) below for details.
+1. The django project configuration.
+1. 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.
+1. Dockerfile used to build the Docker image.
+1. Entrypoint script called by the Docker image.
+1. Django manage.py script. In nearly all cases, there's no good reason to change this. Just leave it alone.
+1. Requirements.in file used by `uv pip compile`. See the [uv tool](uv.md) for details.
+1. Requirements.txt file generated by `uv pip install`. Do not modify this file. Edit the `requirements.in` file instead. See the [uv tool](uv.md) for details.
+1. 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
+
+```bash
+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.
+1. Permission classes definitions.
+1. Serializers to control what data is sent to the client.
+1. Routes for the API.
+1. Views to retrieve data for the API.
+1. [AppConfig](https://docs.djangoproject.com/en/stable/ref/applications/#application-configuration) for the core app.
+1. Initial data scripts. See [Create initial data scripts](create-initial-data-migrations.md) for how to create these.
+1. Migration scripts. These are generated by the `makemigrations` command.
+1. File used by `django-linear-migrations`. It stores the last migration name for the app for use in git merge conflicts.
+1. Models for the core app.
+1. Scripts for the core app. We use it to hold temporary scripts in [Create initial data migrations](create-initial-data-migrations.md), but there's no need to commit them into git.
+1. Test fixtures file
+1. Test for the API
+1. Test for the models
+1. Test for the permissions
+1. Utility scripts for the core app
+1. Utility functions supporting JWT with Cognito
+
+#### Data App
+
+```bash
+data/
+└── migrations/
+.   ├── nnnn_migration_name.py # (1)!
+.   ├── ...
+.   └── max_migration.txt # (2)!
+```
+
+1. Migration scripts. See [Create initial data migrations](create-initial-data-migrations.md) for how to create these.
+1. File used by `django-linear-migrations`. It stores the last migration name for the app for use in git merge conflicts.
+
+### Documentation
+
+```bash
+/
+├── 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.
+1. 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.
+1. Home page of the documentation site. This files uses a snippet to import the `README.md` file from the project root.
+1. 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.
+1. 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.
+1. Contributing file for the project. This name is capitalized according to Github conventions.
+1. Licence file for the project. This name is capitalized according to Github conventions.
+1. MkDocs config file.
+1. README file for the project. This name is capitalized according to Github conventions.

docs/tools/scripts.md

@@ -2,18 +2,49 @@
 
 These are designed to make it easier to perform various everyday tasks in the project. They try to be transparent by exposing the underlying commands they execute so that users can have an idea of what's happening and try to learn the commands if they wish.
 
+```bash
+scripts/
+├── buildrun.sh
+├── check-migrations.sh
+├── createsuperuser.sh
+├── db.sh
+├── erd.sh
+├── lint.sh
+├── loadenv.sh
+├── logs.sh
+├── migrate.sh
+├── precommit-check.sh
+├── run.sh
+├── start-local.sh
+├── test.sh
+└── update-dependencies.sh
+```
+
 These scripts assume you are using bash.
 
 1. **buildrun.sh** - clean, build, and run containers in background mode
 
     1. Pass in `-v` to remove data volume, which resets the local database.
     1. See the script file for more options.
 
-1. **lint.sh** - lint and and auto-format code
+1. **check-migrations.sh** - check if migrations are up to date
 
-1. **test.sh** - run tests and generate test coverage report
+1. **createsuperuser.sh** - create a default superuser
+
+    1. This assumes that `DJANGO_SUPERUSER_USERNAME` and `DJANGO_SUPERUSER_PASSWORD` are set in `.env.dev`
+
+1. **db.sh** - connect to the database in the `db` container
 
-    1. Use the `-k` flag to filter tests. For example `test.sh -k program_area` will select only tests with "program_area" in the name. The coverage report will show many missing lines of coverage as a result. We recommend adding `--no-cov` in this case to disable the coverage report.
+    1. This is a different route than `manage.py dbshell`, which requires the `psql` executable in the `web` container
+
+1. **erd.sh** - generate ER diagram
+
+    - The image is saved to `app/erd.png`
+    - This script is dependent on the `graphviz` package
+
+1. **lint.sh** - lint and and auto-format code
+
+1. **loadenv.sh** - load environment variables from `.env.dev` into shell environment
 
 1. **logs.sh** - view/tail container logs
 
@@ -23,13 +54,17 @@ These scripts assume you are using bash.
 
 1. **precommit-check.sh** - sanity checks before committing code
 
-1. **createsuperuser.sh** - creates a default superuser.
+    1. Call `buildrun.sh`, `lint.sh`, and `test.sh`
 
-    1. This assumes that `DJANGO_SUPERUSER_USERNAME` and `DJANGO_SUPERUSER_PASSWORD` are set in `.env.dev`
+1. **run.sh** - start the development server in Docker, with some options
 
-1. **erd.sh** - generate ER diagram
+    1. Pass in `-h` to show usage
 
-    - The image is saved to `app/erd.png`
-    - This script is dependent on the `graphviz` package
+1. **start-local.sh** - start the development server natively
+
+1. **test.sh** - run tests and generate test coverage report
+
+    1. Use the `-k` flag to filter tests. For example `test.sh -k program_area` will select only tests with "program_area" in the name.
+    1. Pass in `--no-cov` to disable the coverage report. The coverage report will show many missing lines of coverage as a result.
 
 1. **update-dependencies.sh** - update python dependencies to the latest versions