Overview

Relevant source files

• REUSE.toml
• base/static/css/base-style.css
• base/static/css/index-style.css
• base/static/img/OpenEnergyFamily_OEPlatypus.png
• base/static/img/welcome/about-community.svg
• base/static/img/welcome/about-openscience.svg
• base/static/img/welcome/about-process-modelling.svg
• base/static/img/welcome/ontology.svg
• base/static/oeplogo.svg
• base/templates/base/404.html
• base/templates/base/500.html
• base/templates/base/_header.html
• base/templates/base/base-full.html
• base/templates/base/base-profile.html
• base/templates/base/base-sidebar.html
• base/templates/base/base-wide-react.html
• base/templates/base/base.html
• base/templates/base/index.html
• base/templates/base/messages.html
• base/templates/base/oefamily-sc.html
• base/urls.py
• base/views.py
• oeplatform/settings.py
• oeplatform/urls.py
• ontology/templates/ontology/about.html
• ontology/templates/ontology/class.html
• ontology/templates/ontology/oeo.html
• ontology/templates/ontology/partial_ontology_full.html
• ontology/templates/ontology/partial_ontology_sidebar_content.html
• ontology/urls.py
• ontology/views.py
• requirements.txt
• theming/scss/layouts/_ontology.scss

The Open Energy Platform (OEP) is a collaborative web application for managing, annotating, and sharing energy system modeling data and knowledge. It serves as the central platform of the Open Energy Family, providing structured database tables, rich metadata management, semantic ontology integration, and research factsheets to support transparent and FAIR (Findable, Accessible, Interoperable, Reusable) energy system analysis.

This document provides a high-level introduction to the codebase architecture, main components, and navigation guide. For detailed information about specific subsystems, refer to the linked sections throughout this page.

Related documentation:

• For system architecture details, see System Architecture
• For installation and setup, see Installation and Configuration
• For development practices, see Development Guide

Purpose and Scope

The Open Energy Platform serves three primary user groups:

1. Data Contributors: Researchers who upload, document, and publish energy-related datasets with standardized metadata
2. Data Consumers: Analysts who discover, access, and download datasets through web interface or REST API
3. Knowledge Curators: Domain experts who maintain ontologies, create factsheets, and perform peer reviews

The platform combines:

• Relational database management (PostgreSQL-based)
• Semantic knowledge representation (OWL ontologies, RDF triple stores)
• Collaborative workflows (peer review, permissions, groups)
• Multiple presentation layers (web UI, REST API, SPARQL endpoints)

Sources: base/templates/base/index.html1-150 oeplatform/settings.py1-452 base/views.py36-39

Technology Stack

Key Technologies:

Component	Technology	Version	Purpose
Web Framework	Django	5.1.15	Core application framework
API Layer	Django REST Framework	3.15.2	RESTful API endpoints
Database	PostgreSQL	-	Relational data storage
ORM	SQLAlchemy	1.3.24	Advanced query operations
Authentication	django-allauth	65.2.0	User registration/login
Frontend (Traditional)	Bootstrap 5 + jQuery + HTMX	-	Server-rendered UI
Frontend (Modern)	React + Vite	-	Complex SPAs
RDF/OWL	rdflib, owlready2	7.0.0, 0.45	Ontology processing
Metadata Validation	omi, oemetadata	1.1.0, 2.0.4	Schema validation

Sources: requirements.txt1-62 oeplatform/settings.py129-168 oeplatform/settings.py360-376

Repository Structure

Directory Overview:

Directory	Purpose	Key Files
oeplatform/	Django project configuration	settings.py, urls.py, wsgi.py
dataedit/	Table CRUD, metadata editor	views.py, models.py, forms.py
api/	REST API implementation	views.py, actions.py, parser.py
factsheet/	Scenario bundles (RDF-based)	views.py, models.py, schema.py
modelview/	Model/framework factsheets	views.py, models.py, forms.py
ontology/	OEO file serving and browser	views.py, utils.py, urls.py
login/	User auth, permissions, groups	models.py, backends.py, forms.py
base/	Base templates, static files	base.html, views.py, urls.py
theming/	SCSS source files	oepstrap.scss, component partials

Sources: oeplatform/urls.py42-61 oeplatform/settings.py129-168

Main Application Components

Data Management System (dataedit + api)

The highest-importance subsystem (combined importance: 1112.94) handles all table operations.

Key URLs:

• /database/ → Topic/schema listing (dataedit/urls.py)
• /database/{schema}/{table}/ → Table view (dataedit/views.py)
• /api/v0/schema/{schema}/tables/{table}/rows/ → Data API (api/urls.py)

Key Features:

• Table creation wizard with CSV upload
• Inline data editing with validation
• OEMetadata v2.0 schema validation
• Open peer review workflow
• Table publication with DOI assignment

For detailed documentation, see Data Management System.

Sources: oeplatform/urls.py45 Diagram 2 from high-level architecture

Factsheet Systems

Two complementary factsheet types document energy research:

Scenario Bundles (importance: 482.31):

• Complex research documentation with RDF graphs
• Links scenarios → models → data tables
• OEO ontology annotations for semantic interoperability
• OEKG triple store integration
• See Scenario Bundles (Study Factsheets)

Model/Framework Factsheets (importance: 256.43):

• Structured metadata about energy models and frameworks
• CSV export functionality
• Simpler CRUD operations
• See Model and Framework Factsheets

Sources: oeplatform/urls.py53-56 base/templates/base/_header.html41-67

Ontology and Knowledge Graph

Manages the Open Energy Ontology (OEO) and provides semantic search capabilities.

Key URLs:

• /ontology/ → OEO overview (ontology/urls.py25)
• /ontology/oeo/entities/ → Entity search (ontology/urls.py86-90)
• /ontology/oeo/{term_id}/ → Entity details (ontology/urls.py97-101)
• /viewer/oeo/ → OEO Viewer app (oeo_viewer/urls.py)

OEO Integration:

• Files stored at ONTOLOGY_ROOT/oeo/{version}/ (oeplatform/settings.py329-331)
• Served as OWL/RDF downloads
• Used for metadata annotation in data tables
• Powers scenario bundle semantic linking

For detailed documentation, see Ontology and Knowledge Graph.

Sources: ontology/views.py60-306 ontology/urls.py23-102 oeplatform/settings.py329-336

User and Access Management

Comprehensive authentication and permission system.

Authentication Flow:

1. django-allauth handles registration/login (oeplatform/settings.py402-418)
2. Custom backends support email-based login (login/backends.py)
3. django-axes provides brute-force protection (oeplatform/settings.py428-432)
4. CAPTCHA on forms when enabled (oeplatform/settings.py434-435)

Permission System:

• Four levels: NO_PERM (0), WRITE_PERM (4), DELETE_PERM (8), ADMIN_PERM (12)
• Calculated as MAX(user_perm, group_perm, global_admin)
• Applied to tables, metadata, peer reviews
• See Permissions and Groups

Profile Pages:

• /user/{id}/tables/ → Published/draft tables
• /user/{id}/reviews/ → Peer review participation
• /user/{id}/groups/ → Group memberships
• /user/{id}/settings/ → API token, password

Sources: oeplatform/settings.py353-376 oeplatform/settings.py402-432 Diagram 3 from high-level architecture

Request Flow

Understanding how HTTP requests flow through the system:

URL Routing Pattern:

• Root: oeplatform/urls.py42-61
• Includes sub-apps with namespaces (dataedit:, api:, ontology:, etc.)
• Each app defines own urls.py with app_name set

Middleware Stack:

1. SessionMiddleware → Manages user sessions
2. AuthenticationMiddleware → Identifies user
3. AxesMiddleware → Brute-force protection
4. CorsMiddleware → CORS headers for API
5. AccountMiddleware → django-allauth integration

Sources: oeplatform/urls.py1-62 oeplatform/settings.py170-183 Diagram 6 from high-level architecture

Frontend Architecture

Hybrid approach combining traditional server rendering with modern SPAs:

Template Hierarchy:

• base.html: Standard three-column layout (main + sidebar)
• base-profile.html: Profile pages with inverted column order
• base-full.html: Full-width content, no sidebar
• base-sidebar.html: Toggleable sidebar for table views
• base-wide-react.html: Minimal wrapper for React apps

Static Asset Pipeline:

1. SCSS compiled to CSS (theming/scss/)
2. django-compressor bundles and minifies (oeplatform/settings.py387-400)
3. Vite bundles React apps (oeplatform/settings.py51)
4. collectstatic aggregates to STATIC_ROOT

For detailed documentation, see Frontend Architecture.

Sources: base/templates/base/base.html1-105 base/templates/base/base-wide-react.html1-73 oeplatform/settings.py379-400

Configuration and Settings

Critical Settings:

Setting	Purpose	Defined In
DATABASES	PostgreSQL connection	securitysettings.py
RDF_DATABASES	Triple store config	securitysettings.py
ONTOLOGY_ROOT	OEO file directory	securitysettings.py
OEKG_SPARQL_ENDPOINT_URL	Knowledge graph endpoint	securitysettings.py
ONTOP_SPARQL_ENDPOINT_URL	Virtualized SPARQL	securitysettings.py
SCHEMA_DATA	Main data schema name	securitysettings.py
AUTH_USER_MODEL	Custom user model	settings.py:353
EXTERNAL_URLS	Link compendium	settings.py:187-291

Environment-Specific:

• DEBUG: Development mode flag
• ALLOWED_HOSTS: Permitted domains
• SECRET_KEY: Django security key
• USE_ONTOP, USE_LOEP: Feature toggles (oeplatform/settings.py443-444)

Sources: oeplatform/settings.py41-80 oeplatform/settings.py187-291 oeplatform/settings.py329-336

Navigation by Use Case

I want to understand...

Topic	Start Here
How tables are created and edited	Data Management System
How the REST API works	REST API
How metadata is validated	Metadata Management
How peer review works	Open Peer Review System
How scenario bundles use RDF	Scenario Bundles
How the OEO is served	Open Energy Ontology (OEO) Browser
How permissions are calculated	Permissions and Groups
How templates are organized	Template System
How to run tests	Testing Infrastructure
How to deploy	CI/CD Pipeline

I want to modify...

Component	Key Files	Documentation
Table view UI	dataedit/templates/, dataedit/static/	Table Viewing and Editing Interface
API endpoints	api/views.py, api/actions.py	REST API
Upload wizard	dataedit/wizard.py, dataedit/static/js/wizard.js	Data Upload Wizard
Metadata editor	dataedit/static/js/metaedit.js, dataedit/forms.py	Metadata Management
Peer review logic	dataedit/models.py:PeerReview*, dataedit/views.py	Open Peer Review System
Scenario bundle UI	factsheet/, React source	Scenario Bundles
OEO file serving	ontology/views.py, ontology/utils.py	OEO Browser
Authentication	login/backends.py, login/adapters.py	Authentication System
Base templates	base/templates/base/, theming/scss/	Template System, Styling and Theming

Sources: Table of contents from prompt, oeplatform/urls.py42-61

Development Workflow

Quick Start:

1. Install dependencies: pip install -r requirements.txt (requirements.txt1-62)
2. Configure database and settings (see Installation and Configuration)
3. Download OEO files to ONTOLOGY_ROOT/oeo/ directory
4. Run migrations: python manage.py migrate
5. Create superuser: python manage.py createsuperuser
6. Start development server: python manage.py runserver

Testing:

• Run all tests: tox (tox.ini)
• Run specific test: pytest api/tests/test_xyz.py::test_function
• Check coverage: pytest --cov=. --cov-report=html

Code Quality:

• Pre-commit hooks: .pre-commit-config.yaml
• Linting: ESLint (JavaScript), Ruff (Python)
• Formatting: Prettier (JavaScript/CSS)

For detailed setup instructions, see Installation and Configuration. For testing guide, see Testing Infrastructure.

Sources: requirements.txt1-62 REUSE.toml metadata

Key Architectural Patterns

1. Multi-Database Architecture:

• Primary: PostgreSQL for relational data (tables, users, metadata)
• Secondary: RDF triple store for semantic data (scenario bundles, OEKG)
• File system: OWL ontology files

2. Hybrid Frontend Strategy:

• Server-rendered templates with HTMX for progressive enhancement
• React SPAs for complex interactions (scenario bundles, OEO viewer)
• Shared Bootstrap design system for consistency

3. Layered API Design:

• Views handle HTTP requests/responses (api/views.py)
• Actions encapsulate business logic (api/actions.py)
• Parsers translate queries to SQL (api/parser.py)
• Sessions manage database connections

4. Permission-Based Access Control:

• Interface-based design: PermissionHolder
• Multiple sources: direct user permissions, group inheritance, admin override
• Calculated as MAX of all applicable permissions
• Applied consistently across web UI and API

5. Template Inheritance Hierarchy:

• Base templates define common structure
• App templates extend and override blocks
• Partials loaded via HTMX for dynamic updates
• React apps use minimal wrappers

6. Configuration by Convention:

• Django apps follow consistent structure (models, views, forms, urls, templates, static)
• URL namespacing prevents conflicts (dataedit:table-view, api:table-rows)
• Settings organized by concern (database, auth, external services)

Sources: oeplatform/settings.py1-452 Diagram 1 and Diagram 4 from high-level architecture

---

This overview provides the foundational understanding needed to navigate the Open Energy Platform codebase. For detailed information about specific subsystems, consult the linked documentation sections throughout this page.