Documentation

A lightweight Python toolkit created by an IT project manager for IT project managers who need to track and manage multiple projects at a high level.

Who Is This For?

IT project managers with a technical background who manage multiple projects and want automated visibility into:

Project status and progress
Development and production deployments
Task completion rates
Service subscriptions and renewal dates
Version tracking across environments

Technical Requirements

This tool requires a technical background to set up and run. You should be comfortable with:

Python environment setup
Command line operations
Environment variable configuration
Basic Notion API concepts

What Nsynca Does

Nsynca provides modular updaters for high-level project tracking:

Project Dashboard Updates

For each project in your portfolio, Nsynca automatically updates:

Latest deployment version per environment
Last deployment date per environment
Total releases per environment
Task totals and completed counts
Overall project completion status

Service Management

Track all paid services across your projects — from cloud platforms like GCP and AWS to AI tools such as OpenAI, Anthropic, and other subscriptions.

Next Due Date calculation (monthly/yearly billing)
Status tracking: ✅ Active / ⏳ Coming Soon / 🟠 Overdue / 🛑 Cancelled
Automatic billing record creation
Subscription cost tracking

Prerequisites

Notion Setup

Copy our Notion template: Project Management Template
Create a Notion integration at notion.so/integrations
Share database access: Open database → ••• → Connections → Add your integration
Add your projects, tasks, deployments, versions, and services that you want to track

Technical Requirements

Python 3.11.x (not 3.12+)
uv package manager
Docker Desktop
Make:
- Windows: winget install GnuWin32.Make
- macOS: brew install make
- Linux: sudo apt install make

Installation

1. Clone the Repository

git clone https://github.com/lisekarimi/nsynca.git
cd nsynca

2. Set Up Environment

Copy .env.example to .env
Fill in your Notion integration token and database IDs
Install dependencies:

uv sync

Usage

Graphical User Interface

For quick, one-click updates:

make gui

Command Line Interface with Docker

For consistent execution across environments:

make build
make run
make deploy
make task
make service
marle charge

Windows Executable

Build standalone .exe for team distribution:

make build-exe    # Generate spec file
make compile-exe  # Create executable

Find executable in dist/ folder.

Automation

Schedule Nsynca to run automatically:

Windows: Task Scheduler
macOS/Linux: cron jobs

Recommended: Run daily to keep project dashboards current for management reviews.

Logs & Monitoring

Log Locations

Development: logs/ in project root
Executable: dist/logs/ next to the .exe file

Viewing Logs

Open the GUI to browse logs from previous runs
Filter by month, update type, or status (success/failed)
Track which projects were updated and when
Identify any sync issues that need attention

Development & Maintenance

Code Quality

make lint        # Check code quality
make fix         # Auto-fix formatting issues
make install-hooks  # Install pre-commit hooks

Security

Gitleaks integration for secret scanning
Automated security checks via GitHub Actions

Customization

The toolkit is modular and extensible. IT managers with Python experience can:

Add custom updaters for additional databases
Modify field mappings to match their Notion setup
Extend logging and reporting capabilities
Integrate with other project management tools

Changelog

See the full update history on GitHub →