inventree/InvenTree
2
0
Fork 0
mirror of https://github.com/inventree/InvenTree.git synced 2025-07-21 12:16:29 +00:00
Code Activity

feat(docs): add architecture/roadmap (#9624)

Browse Source 
* feat(docs): Add architecture overview

* add strucutre for rough roadmap

* add stable reference

* document stable links

* test mermaid again

* fix loading

* fix format to reduce warnings

* use local js

* add architecture ovierview

* add more sub-points

* more structure

* add general backend text

* add sme bqsic docs for frontend

* fix list syntax

* fix typo
This commit is contained in:
Matthias Mair
2025-06-13 03:28:02 +02:00
committed by GitHub
parent c70583097c
commit 4b1eeefb1f
12 changed files with 2796 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
docs/docs/develop/architecture.md Normal file
View File

@@ -0,0 +1,81 @@
---
title: Architecture
---
## Typical Deployment
InvenTree is a classical Django Application and supports the WSGI interface standard. The following diagram shows a typical and recommended deployment architecture of InvenTree.
``` mermaid
flowchart LR
Request --- RP[1: Reverse Proxy]
RP --- Gunicorn[5: Gunicorn]
subgraph image:inventree/inventree
Gunicorn --- Django[6: Django Server processes]
end
Django --- Database@{ shape: cyl, label: "SQL Database" }
Django --- Redis
Worker[7: Q2 Worker] --- Redis@{ shape: cyl, label: "9: Redis Cache" }
Database -- 8: DB holds tasks ---> Worker
subgraph caddy
RP --- file[2: file server]
end
file --- s[3: Static Files]
file --- m[Media Files]
RP-. 4: API auth request .-> Gunicorn
```
1. A Request is received by a reverse proxy (e.g. Caddy, Nginx, Apache).
2. Requests for static or media files are either served directly by the reverse proxy or forwarded to a dedicated file server
3. Static or media files can be served by the different file server (placing static files in a CDN for example)
4. Media files require an API authentication request to the Django server to ensure the user has access to the file
5. API or frontend requests are forwarded from the reverse proxy to Gunicorn, which is a WSGI server that handles server Django processes.
6. The Gunicorn processes are loosely coubled instances of Django application - which mainly serves a REST API as the frontend only needs a few full django calls (see [frontend architecture](#frontend-architecture) below).
7. A properly configured InvenTree instance will also run background workers (Q2 Worker) which are responsible for processing long-running tasks, such as sending notifications, generating reports or calculating expensive updates. Q2 is used as the task processing library, which runs multiple loosely coupled worker processes.
8. The database holds tasks and is queried by the workers. This enables relatively durable task processing, as the underlying server can be restarted with minimal task loss.
9. Various components of InvenTree can benefit from a Redis or protocol compatible cache, which is used to store frequently accessed data, such as user sessions, API tokens, global or plugin settings, or other transient data. This can help to improve performance and reduce load on the database.
## Code Architecture
This sections describes various architectural aspects of the InvenTree codebase and mechanisms and lifecycles in the system.
Knowledege of these aspects is not required to use InvenTree, but it is helpful for developers who want to contribute to the project or to understand where / how one might extend the system with plugins or by pathching in custom functionality.
### Repository layout and separation of concerns
All code that is intended to be executed on the server is located in the `src/` directory. Some code in contrib might be needed to deploy or maintain an instance.
One exception is the `tasks.py` file, that contains definitions for various maintenance tasks that can be run from the command line. This file is located in the root directory of the repository to make instructions easier.
Code styles are generally only applied to the code in the `src/` directory.
### Backend Architecture
InvenTree's backend is a Django application. It is generally structured in a way that follows Django's conventions, but also includes some customizations and extensions to support the specific needs of InvenTree.
Most remarkable deviations from the Django standard are:
- Manipulation of the django app mechanisms to enable the [plugin system](#plugin-system)
- Usage of a custom role-mapping system to make permissions more approachable
The backend aims to be:
- API first, with a RESTful API that is used by the frontend and can also be used by other applications.
- Modular, with a clear separation of concerns between different components and apps.
- Tested reasonably throughout with transparent test coverage
- Following the Django and generally accepted security conventions
### Frontend Architecture
InvenTree's frontend is primarily a single-page application (SPA) built with React, mantine and yarn/vite for bundling.
#### Serving the frontend
It is statically pre-build and is served by the Django application as a bundle of static files. No node executable or bundling technology is required to run the frontend in production. It is however possible to use the development server for the frontend stack together with a development or production instance of the backend.
Frontend and backend do not need to be serverd by the same server or on the same domain, only the API versions need to match.
#### Coupling to the backend
The frontend is not coupled during the lifetime of the application but it can be primed via the `INVENTREE_SETTINGS` global variable (rendered by the `spa_settings` tag).
These settings can configure the base url, available backends, environment details and more.
To facilitate this the html structure for the frontend is run through a performance-optimized template. There is only a very limited amount of rendering done to keep response times and surface for security threads low.

6
docs/docs/develop/contributing.md
View File

@@ -246,6 +246,12 @@ T002: Double quotes should be used in tags
New features or updates to existing features should be accompanied by user documentation.
### Stable link references
The documentation framework enables addition of redirections. This is used to build stable references for linking in external resources.
New references can be added in `docs/mkdocs.yml` in the `redirect_maps` section. Both external targets and documentation pages are possible targets. All references are linted in the docs CI pipeline.
## Translations
Any user-facing strings *must* be passed through the translation engine.

35
docs/docs/develop/roadmap.md Normal file
View File

@@ -0,0 +1,35 @@
---
title: High level roadmap
---
## General goals
## High level Epics
### 1.0
Smaller items can be viewed [on the milestone](https://github.com/inventree/InvenTree/issues?q=is%3Aissue%20milestone%3A1.0.0).
Aiming to stabelise several aspects of the software:
- Only shipping the new frontend and removing reliance on templating
- Stabelize API for client generation
- Making data import- / export-mechanisms more stable
- Updating and Re-Organising documentation to enable CII best practices compliance
### 2.0
Smaller items can be viewed [on the milestone](https://github.com/inventree/InvenTree/issues?q=is%3Aissue%20milestone%3A2.0.0).
*Proposed* goals:
- Reorganise permission system to support more entrerprise structures and reduce unneeded permissions [EPIC](https://github.com/inventree/InvenTree/issues/7466)
- Add generalised file handling [EPIC](https://github.com/inventree/InvenTree/issues/5703)
### Future
There are several epics that target [the horizion](https://github.com/inventree/InvenTree/issues?q=is%3Aissue%20state%3Aopen%20type%3AEpic).
## Non-Goals
TBD