Merge pull request #739 from Nickatak/docs/add-docstrings

docs: Add docstring conventions and apply across backend + frontend

Author: RSkuma

CONTRIBUTING.md

@@ -37,9 +37,18 @@ The Python codebase has `mypy` running in **gradual mode** — `disallow_untyped
 - **Existing code you touch**: if you're already editing a function for another reason, adding annotations is welcome but not required.
 - **Don't annotate just to silence mypy.** If a type is genuinely ambiguous (`Any` is fine, `# type: ignore[code]` with the specific code is fine when you know why), say so explicitly rather than papering over it.
 - **Django models**: `django-stubs` and `djangorestframework-stubs` are installed; mypy can check ORM call sites without per-call annotation.
+- **Don't annotate Django model fields.** `name = models.CharField(...)` should stay un-annotated. `django-stubs` reads the field declaration (including `null=True`, `choices=...`, etc.) and synthesizes the correct instance-attribute type via mypy's plugin protocol. Manual annotations duplicate that work and drift from the field-level config (e.g. flipping `null=True` without updating an `Optional[str]` annotation). Annotate methods, helper functions, and custom managers as normal.
 
 The goal is that contributors can land work without fighting the type checker, while the typed surface grows incrementally where it pays for itself.
 
+### Docstrings (backend)
+
+Backend code follows a labeled-section docstring convention modeled on the project's sister codebase (BNC). The shape is per-file-kind: heavy labeled templates for models and views (where there's substantive policy to document), lighter prose for serializers and config files. See [docs/developer/backend-docstring-style.md](docs/developer/backend-docstring-style.md) for the full templates, vocabulary, and rationale.
+
+### Docstrings (frontend)
+
+Frontend code uses JSDoc with a different shape from the backend: **heavy on the module level, light at the per-export level**. The file header is the primary place for context (what the file does, why, design decisions); per-export comments are one-liners unless behavior is non-obvious. See [docs/developer/frontend-docstring-style.md](docs/developer/frontend-docstring-style.md) for the per-kind templates and examples.
+
 If an issue takes much longer than its size suggested, post an update on the issue with an honest read on whether you can finish; releasing it back to the backlog is fine.
 
 ### Frontend vs backend issues

backend/backend/asgi.py

@@ -1,10 +1,17 @@
-"""
-ASGI config for backend project.
+"""ASGI config for the backend project (the entry point used by `daphne`).
+
+In CTJ this module is the production entry point - `entrypoint.sh`
+runs `daphne -b 0.0.0.0 -p 8000 backend.asgi:application` to start
+the server. The dev server (`python manage.py runserver`) also
+routes through ASGI here because `daphne` is first in
+`INSTALLED_APPS`, which makes Django's `runserver` use daphne's
+ASGI handler instead of the default WSGI one.
 
-It exposes the ASGI callable as a module-level variable named ``application``.
+Exposes the ASGI callable as a module-level variable named
+`application`.
 
-For more information on this file, see
-https://docs.djangoproject.com/en/5.0/howto/deployment/asgi/
+For more on ASGI deployment:
+https://docs.djangoproject.com/en/6.0/howto/deployment/asgi/
 """
 
 import os

backend/backend/settings.py

@@ -1,13 +1,34 @@
-"""
-Django settings for backend project.
-
-Generated by 'django-admin startproject' using Django 5.0.6.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/5.0/topics/settings/
-
-For the full list of settings and their values, see
-https://docs.djangoproject.com/en/5.0/ref/settings/
+"""Django settings for the CTJ backend project.
+
+Settings are read from environment variables via `python-decouple`'s
+`config()` function. Required vars (no default - server fails to
+start if missing): `SECRET_KEY`, `SQL_ENGINE`, `SQL_DATABASE`,
+`SQL_USER`, `SQL_PASSWORD`, `SQL_HOST`, `SQL_PORT`. Optional vars
+with defaults are inline below. Per
+`project_envvars_owned_by_devops`, CTJ engineering declares the
+vars; devops populates the values per environment (incubator
+repo).
+
+Notable choices:
+- `AUTH_USER_MODEL = "ctj_api.CustomUser"` (subclasses
+  `AbstractUser` rather than extending the default User).
+- `daphne` is first in `INSTALLED_APPS` so Django's `runserver` and
+  the production server both route through ASGI - see
+  `backend.asgi`.
+- `whitenoise` serves static files; the `immutable_file_test`
+  function below identifies hashed asset filenames so they can be
+  served with long-cache headers.
+- HSTS controls are env-driven; defaults are off so dev/stage stay
+  unaffected. Production is expected to set `HSTS_ENABLED=True` and
+  the three `*_SECURE`/`SECURE_*` flags below.
+
+A few config remnants here are dead post-rewrite (template dir
+references to a no-longer-existent `frontend_dist`, plus a
+whitenoise storage workaround). See `scratch/bugs.md` (BUG-007 and
+BUG-010) for the full bug list.
+
+For Django settings reference:
+https://docs.djangoproject.com/en/6.0/ref/settings/
 """
 
 import re
@@ -167,7 +188,19 @@
 # Whitenoise settings
 # http://whitenoise.evans.io/en/stable/django.html#WHITENOISE_IMMUTABLE_FILE_TEST
 def immutable_file_test(path, url):
-    # Match vite (rollup)-generated hashes, à la, `some_file-CSliV9zW.js`
+    """Identify static files with hashed names for whitenoise's immutable-cache headers.
+
+    Matches filenames where the segment immediately before the
+    extension looks like a content hash (8-12 alphanumeric chars,
+    separator preceded by `.` or `-`). Examples that match:
+    `app-CSliV9zW.js`, `chunk.abc12345.css`.
+
+    Note: the original regex was tuned for Vite/rollup-style hashes
+    (the dropped pre-rewrite frontend). Whether it correctly matches
+    Next.js/webpack hashes depends on the chunk-naming output of the
+    current build - and post-rewrite the backend doesn't serve the
+    frontend's static files anyway. See BUG-008 in scratch/bugs.md.
+    """
     return re.match(r"^.+[.-][0-9a-zA-Z_-]{8,12}\..+$", url)
 
 

backend/backend/urls.py

@@ -1,18 +1,22 @@
-"""
-URL configuration for backend project.
+"""Top-level URL routing for the backend Django project.
+
+Three top-level mounts:
+- `/admin/` for the Django admin site.
+- `/api/` delegates to `ctj_api.urls` for all CTJ API routes.
+- Everything else falls through to the SPA catchall in
+  `backend.views`, which serves an HTML template.
+
+Order matters: the SPA catchall is last so the explicit `/admin/`
+and `/api/` mounts win first.
 
-The `urlpatterns` list routes URLs to views. For more information please see:
-    https://docs.djangoproject.com/en/5.0/topics/http/urls/
-Examples:
-Function views
-    1. Add an import:  from my_app import views
-    2. Add a URL to urlpatterns:  path('', views.home, name='home')
-Class-based views
-    1. Add an import:  from other_app.views import Home
-    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
-Including another URLconf
-    1. Import the include() function: from django.urls import include, path
-    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
+Architectural note: the SPA catchall is a remnant from the
+pre-rewrite monolithic setup, when Django served both the API and
+the rendered SPA shell from one process. The post-rewrite
+architecture runs the frontend as a separate Next.js container that
+handles all non-API traffic; anyone hitting the backend service
+directly at a non-`/admin/`, non-`/api/` path is probably misrouted.
+The catchall is preserved for now but is a candidate for removal -
+deferred out of this docs-only PR.
 """
 
 from django.contrib import admin

backend/backend/views.py

@@ -1,8 +1,32 @@
-from django.conf import settings
-from django.views.generic import TemplateView
-
-catchall_dev = TemplateView.as_view(template_name="dev-mode.html")
-
-catchall_prod = TemplateView.as_view(template_name="index.html")
-
-catchall = catchall_dev if settings.DEBUG else catchall_prod
+"""Top-level Django views for the backend project.
+
+Currently only the SPA catchall lives here, used by `backend.urls`'s
+final catch-all `re_path` to serve an HTML template for non-API
+requests. See the architectural note in `backend.urls` - this entire
+file is a candidate for removal post-rewrite.
+
+Two flags worth knowing about:
+
+1. The branch between `catchall_dev` and `catchall_prod` is evaluated
+   at module-import time (the `if settings.DEBUG` runs once when this
+   module first loads). Toggling `DEBUG` at runtime will NOT swap the
+   template; the server must be restarted.
+
+2. `index.html` (the production template) does not exist in
+   `backend/templates/backend/`. In `DEBUG=False`, `catchall_prod`
+   would resolve to that missing template and raise
+   `TemplateDoesNotExist` on any matching request. The dev template
+   (`dev-mode.html`) does exist. This is a real bug, not just a docs
+   note - probably wants the file removed entirely once the SPA
+   catchall is dropped, or a real `index.html` placeholder added.
+   Deferred out of this docs-only PR.
+"""
+
+from django.conf import settings
+from django.views.generic import TemplateView
+
+catchall_dev = TemplateView.as_view(template_name="dev-mode.html")
+
+catchall_prod = TemplateView.as_view(template_name="index.html")
+
+catchall = catchall_dev if settings.DEBUG else catchall_prod

backend/backend/wsgi.py

@@ -1,10 +1,17 @@
-"""
-WSGI config for backend project.
+"""WSGI config for the backend project (currently unused).
+
+CTJ runs `daphne` (an ASGI server) in dev, stage, and prod, so
+this WSGI entry point is unreferenced today. Django's
+`startproject` generates this file by default; it's preserved
+here in case CTJ ever switches to a WSGI-only server (gunicorn,
+uwsgi). If the ASGI choice is permanent, this file can be
+removed; deferred out of this docs-only PR.
 
-It exposes the WSGI callable as a module-level variable named ``application``.
+Exposes the WSGI callable as a module-level variable named
+`application`.
 
-For more information on this file, see
-https://docs.djangoproject.com/en/5.0/howto/deployment/wsgi/
+For more on WSGI deployment:
+https://docs.djangoproject.com/en/6.0/howto/deployment/wsgi/
 """
 
 import os

backend/ctj_api/admin.py

@@ -1,3 +1,22 @@
+"""Django admin registrations for CTJ's domain models.
+
+All seven models are registered with the default `ModelAdmin` (no
+customization). Effect: admins see every field on every row, with
+no list filters, search fields, or read-only protections. This is
+enough for Stage 1 curation of the admin-managed reference tables
+(`Skill`, `Role`, `Project`, `CommunityOfPractice`) plus emergency
+edits to user records and opportunities.
+
+If a model's admin needs filters, list display, or search later,
+register it with a dedicated `ModelAdmin` subclass instead of the
+default.
+
+`SkillMatrix` is registered here even though its model docstring
+classifies it as `internal` (no direct API endpoint). Admin
+exposure lets staff view and edit the underlying JSON blob
+directly, which is useful for debugging matching-algorithm inputs.
+"""
+
 from django.contrib import admin
 
 from .models import (
@@ -10,7 +29,6 @@
     SkillMatrix,
 )
 
-# Register your models here.
 admin.site.register(CommunityOfPractice)
 admin.site.register(Role)
 admin.site.register(Skill)

backend/ctj_api/apps.py

@@ -2,5 +2,14 @@
 
 
 class CtjApiConfig(AppConfig):
+    """Django app config for `ctj_api`, the project's only domain app.
+
+    `default_auto_field` is set to `BigAutoField` to silence Django's
+    startup warning about implicit auto field selection, but in
+    practice it's unused: every CTJ model declares its own
+    `UUIDField` primary key, so no model relies on this default.
+    Carried for parity with Django's scaffold; harmless to leave.
+    """
+
     default_auto_field = "django.db.models.BigAutoField"
     name = "ctj_api"