Apheleia Project Management

Apheleia Project Management is a lightweight project planning and tracking tool developed in Python.

Projects, milestones, resources, workpackages and tasks are described in plain YAML files.
A single command reads those files and generates a static, interactive HTML report containing timelines,
resource allocations and task progress.

Because the plan is just text, it can live in the same repository as the work it describes - reviewed,
diffed and merged like any other source file.

---

📊 Features

• Project timelines, with milestones and today's date marked
• Task status by milestone, and tasks that have grown past their original estimate
• Workpackage timelines and the effort allocated to each
• Resource availability, and how each resource is allocated across projects and workpackages
• Task timelines, progress and forecast completion dates based on effort spent and remaining
• Interactive plotly charts at monthly, quarterly or yearly scale
• Click any name in a table or bar in a chart to navigate to its page
• Static HTML output - no server, no database

Input files

All inputs are YAML files with a type and a list of data. The input directory is searched recursively and
all definitions of the same type are combined, so the plan can be one file per type or split by owner.

Type	Defines
milestones_definitions	Named checkpoints shared by all projects
resources_definitions	People and when they are available
projects_definitions	Projects, their dates and milestone dates
workpackages_definitions	Areas of work and the resources allocated to them
tasks_definitions	Individual tasks and their status history (effort spent and remaining)

type: "milestones_definitions"
data:
  - milestone: "M0"
    description: "Project Definition"

See the documentation for the full field reference.

Generating a report

apheleia_project_report --input <input directory> --html <output directory>
<browser> <output directory>/index.html

--input defaults to . and --html to ./html.

NOTE: The charting and table libraries are loaded from their public CDNs, so an internet connection is required to view the report.

---

📦 Installation

Install from Source

git clone https://github.com/projectapheleia/apheleia-project-management.git
cd apheleia-project-management

# Standard build
pip install .

# Development build
pip install .[dev]

Alternatively if you want to create a virtual environment rather than install globally a script is provided. This will install, with edit privileges to local virtual environment.

This script assumes you have Graphviz installed, so the documentation will build out of the box.

git clone https://github.com/projectapheleia/apheleia-project-management.git
cd apheleia-project-management
source setup.sh

📖 Documentation

In order to build the documentation you must have installed the development build.

Build from Source

cd doc
make html
<browser> build/html/index.html

🏃 Examples

To build the report for all examples:

cd examples

# To build
make report

# To clean
make clean

To build an individual example:

cd examples/THE EXAMPLE YOU WANT

# To build
make report

# To clean
make clean

Example	Description
simple	Minimal semiconductor project, one file per type. The best starting point for a new plan
construction_single	Multi-year construction project, one file per type
construction_multi	The same construction project, split into shared definitions and a tasks file per resource

---

🧹 Code Style & Linting

This project uses Ruff for linting and formatting.

Check code for issues:

ruff check .

Automatically fix common issues:

ruff check . --fix

📧 Contact

• Email: avl@projectapheleia.net
• GitHub: projectapheleia