Metadata-Version: 2.1
Name: django-microsys
Version: 1.19.1
Summary: Django microSYS (System Integration Service) - Multilingual Django Starter Pack, Packed with Features.
Author-email: DeBeski <debeski1@gmail.com>
License: NON-COMMERCIAL
Project-URL: Homepage, https://github.com/debeski/django-microsys
Keywords: django,microsys,permissions,authentication
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=5.1
Requires-Dist: django-crispy-forms>=2.4
Requires-Dist: django-tables2>=2.7
Requires-Dist: django-filter>=24.3
Requires-Dist: crispy-bootstrap5>=2025.6
Requires-Dist: pyotp>=2.9
Requires-Dist: qrcode>=8.2
Requires-Dist: pillow>=11.0
Requires-Dist: babel>=2.1

# Django microSYS - System Integration Service

[![PyPI version](https://badge.fury.io/py/django-microsys.svg)](https://pypi.org/project/django-microsys/)

<p align="center">
  <img src="https://raw.githubusercontent.com/debeski/django-microsys/main/microsys/static/img/login_logo.webp" alt="microSys Logo" width="450"/>
</p>

microSYS is a multilingual Django app that gives a project-level system layer for user management, branding, translations, scopes, navigation, activity logging, guided onboarding, data export, and dynamic CRUD tooling. It is not just a themed admin shell: it is a fairly large internal-systems toolkit that bundles runtime configuration, user operations, auditability, UI infrastructure, and zero-boilerplate management patterns into one package. The package now keeps the landing README short and moves the long-form operating and integration guidance into [`docs/`](docs/README.md).

## What microSYS gives you

- A first-launch setup wizard at `/sys/setup/` for branding, languages, themes, global home URL, and sidebar structure.
- A runtime system UI for users and superusers, including Options, user management, profiles, 2FA, activity logs, scopes, and system settings.
- A database-backed `SystemSettings` singleton layered over `MICROSYS_CONFIG`, so projects can seed defaults in code and refine them in the UI later.
- A `ScopedModel` base with audit fields, soft-delete behavior, actor tracking, filtered managers, and automatic scope handling.
- Zero-boilerplate sections and dynamic modal CRUD flows for auxiliary models, plus a reusable context-menu/event model for richer interactions.
- A built-in audit trail with signal-based logging, merged User/Profile updates, diff capture, masked sensitive fields, and download/export log entries.
- Universal data helpers such as `fetch_file`, `fetch_excel`, sticky-form autofill, tutorial overlays, and persistent UI preferences.

## Requirements

- Python 3.11+
- Django 5.1+
- `django-crispy-forms`
- `crispy-bootstrap5`
- `django-tables2`
- `django-filter`
- `pillow` "for image handling"
- `babel` "for translations"
- `psutil` "for system monitoring"
- `pyotp` "for TOTP 2FA"
- `qrcode` "for TOTP 2FA QR codes"

## Installation

```bash
pip install django-microsys
# OR
pip install git+https://github.com/debeski/django-microsys.git
```

## Minimal Quick Start

1. Add the MicroSys helper at the end of your project `settings.py`.

```python
from microsys.utils import microsys_settings

microsys_settings(globals())
```

That helper prepends the required apps, inserts `microsys.middleware.ActivityLogMiddleware` after Django authentication middleware when present, adds the Microsys context processor, sets the Crispy Bootstrap 5 defaults, and seeds the standard MicroSys runtime defaults for language, timezone, i18n/tz flags, `FORMAT_MODULE_PATH`, and charset unless your project already defines them.

__Proceed to [Getting Started](docs/getting-started.md) if you prefer to wire everything manually.__


2. Mount `microsys.urls` at project root so the bundled auth and system routes stay at `/accounts/...` and `/sys/...`.

```python
from django.urls import include, path

urlpatterns = [
    path("", include("microsys.urls")),
]
```

With that root include in place, microsys provides `/accounts/...` and `/sys/...`. If your project does not define its own `/` view, microsys falls back from an unresolved `/` request into its login/setup flow instead of leaving a 404. On a fresh and unconfigured install, Microsys also guards ordinary anonymous requests so a public root page cannot bypass first-time setup; once setup is complete, your existing root view continues to behave normally.

3. Run the setup command.

```bash
python manage.py microsys_setup
```

4. Sign in as a superuser and complete the first-launch wizard at `/sys/setup/`. On a fresh install, an anonymous request may be sent through `/sys/setup/` and then to login before the wizard can be completed. After setup, the main runtime UI lives under `user_hub`.

For a fuller setup path, prefix-mount guidance, and first-launch expectations, use the [Getting Started guide](docs/getting-started.md).

## Key Capabilities

- Onboarding and runtime configuration:
  first-launch setup wizard, Options view, runtime System Settings modal, language/theme defaults, translation overrides, and a global Home destination.
- User and security operations:
  interactive user wizard, grouped translated permissions, profile management, multiple 2FA flows, backup codes, and runtime preference persistence.
- Generic CRUD infrastructure:
  dynamic sections, AJAX-driven modal CRUD, automatic form/table/filter discovery, context-menu actions, and reusable event dispatch.
- Navigation and UI infrastructure:
  resolver-driven sidebar builder, runtime tree rendering, user-level reordering, tutorial overlays, theme-aware system surfaces, and template injection hooks.
- Data movement and productivity helpers:
  universal file download, Excel export, smart autofill, sticky-form cloning, and generic list/filter helpers.
- Audit and governance:
  signal-based activity logging, diff capture, masked sensitive fields, deduplicated entries, download/export logging, and scoped visibility.
- Framework-level automation:
  translation patches, scoped-model auto-injection, actor tracking, soft-delete, and config layering across defaults, project settings, and runtime UI.

## Documentation

- [Documentation Hub](docs/README.md)
- [Getting Started](docs/getting-started.md)
- [Admin Guide](docs/admin-guide.md)
- [Developer Guide](docs/developer-guide.md)
- [Customization Guide](docs/customization-guide.md)
- [Reference](docs/reference.md)
- [Changelog](CHANGELOG.md)

## Maintenance

microSYS documentation now follows a simple rule:

- Evergreen usage and customization docs live under [`docs/`](docs/README.md).
- Release-by-release history lives in [`CHANGELOG.md`](CHANGELOG.md).

That keeps the landing page easy to scan while still giving the project a thorough in-repo manual.
