Project Structure

This page explains how the RDMC Creation Workflow platform codebase is organized: architectural terminology, repository layout, component structure, and where files belong within a component.

See Component Diagram for the architecture views and component diagrams, and Architecture for the high-level system overview and layer responsibilities.

Architectural Terminology

Term

Definition

Component

A self-contained package with one clear responsibility.

Configuration package

Wires all components together: global settings and entry points.

Package / Sub-package

An importable namespace of related modules (handlers/, helpers/, migrations/).

Module

A single .py file — the smallest unit of code organization.

Directory

A folder grouping non-code assets (docs/, etc/, vendor/).

Service

An independent, externally running unit of functionality that provides one specific capability to the core container lifecycle through a well-defined interface.

Layer

A logical grouping of platform components by one shared responsibility. Layers are separate from each other and communicate through defined interfaces.

Repository Layout

All code lives under src/. The repository root holds configuration, documentation, tests, and entry points.

rdmc-prototype/
├── src/                       # Source code directory
│   ├── RDMC_Proto/            # Project configuration package
│   └── <component>/           # System components
├── test/                      # Test cases
├── docs/                      # Versioned documentation
├── etc/                       # Environment and service configuration files
├── vendor/                    # Vendored third-party assets and schemas
├── manage.py                  # CLI entry point
├── startup.py                 # Production server entry point
├── Makefile                   # Command runner and task automation shortcuts
├── pyproject.toml             # Project metadata, dependencies, and tool settings
├── Dockerfile                 # Container image build specification
├── docker-compose.yml         # Local multi-container development configuration
├── .gitlab-ci.yml             # GitLab CI/CD pipeline definitions
├── .env.example               # Environment variables configuration template
├── .gitignore                 # Files and directories ignored by Git
├── .dockerignore              # Files excluded from Docker build context
├── README.md                  # Project overview and getting started guide
├── CHANGELOG.md               # Release history and version changes
├── CONTRIBUTING.md            # Guidelines for project contributors
├── CODE_OF_CONDUCT.md         # Community standards and code of conduct
├── CITATION.cff               # Citation metadata for research referencing
├── LICENSE                    # Project software license terms
└── SECURITY.md                # Security policy and vulnerability reporting

The src/ directory is placed on the import path by manage.py, startup.py, RDMC_Proto/wsgi.py, and RDMC_Proto/asgi.py; the Docker image adds /app/src to the import path.

Component Structure

Every component follows a uniform layout:

<component>/
├── __init__.py               # Marks the directory as a package
├── models.py                 # Data models and database schemas
├── urls.py                   # URL routing mapped to views
├── views.py                  # Entry points
├── migrations/               # Database schema migrations
├── handlers/                 # Self-contained business workflows
├── helpers/                  # Reusable support utilities
├── templates/                # HTML page templates
└── static/                   # Frontend assets (CSS, JS, images)

Only ship what the component requires. Centralized admin registrations live in rdmc_management/admin.py.

Handlers vs. Helpers — Where Does a File Go?

  • handlers/ → Complete workflows:

    • Executes a full business operation from start to finish. May accept requests and return responses.

    • Rule: Does this file execute a complete workflow end-to-end? → handlers/.

  • helpers/ → Reusable support logic:

    • Provides building blocks and shared utilities called by handlers or views. Never performs a complete workflow alone.

    • Rule: Is this file a supporting tool used by other code? → helpers/.