feat: improve the concepts docs

docs/concepts/core.md

@@ -0,0 +1,103 @@
+# Fundamentals & Core Concepts
+
+## Organizations
+
+In OpenCVE, an **Organization** is the highest-level object. It represents your company or your team in OpenCVE. All resources — projects, users, subscriptions, notifications, and API usage — are managed at the organization level.
+
+Each user can belong to one or more organizations, with one of the following two roles:
+
+- **Member**, who can manage subscriptions (vendors and products).
+- **Owner**, who has full control over the organization, including managing memberships.
+
+Organizations allow multiple users to collaborate while sharing quotas such as subscriptions and API calls.
+
+![OpenCVE Organizations](../images/opencve-organizations.png){.center style="width:90%"}
+
+## Projects
+
+Projects are the main building blocks of an organization in OpenCVE. Each organization can contain one or more Projects.
+
+A project allows you to:
+
+- Track the technologies you want to monitor for vulnerabilities,
+- Configure notification channels to receive alerts,
+- Generate reports and summaries of CVE activity,
+- Assign users to CVEs and manage their status (e.g., analysis, risk acceptance).
+
+Projects help organizations structure their subscriptions in a way that matches their teams and workflows. Common use cases include:
+
+- **MSSPs** creating a project for each client (e.g., client1, client2, client3),
+- **IT companies** creating projects for different technical teams (e.g., team-X, team-Y, team-Z),
+- **Smaller organizations** splitting projects by role, for example one project for developers and another for sysadmins.
+
+![OpenCVE Projects](../images/opencve-projects.png){.center style="width:70%"}
+
+Each project operates independently, with its own dashboard to track vulnerabilities in its subscriptions. By splitting monitoring into projects, you can scope CVE exposure by product, team, customer, or environment, keeping a clear, focused view of what matters most.
+
+## Notifications
+
+Notifications are alerts triggered whenever a CVE appears or an existing CVE is updated, **and the CVE affects one of your tracked technologies (subscriptions)**. They ensure you stay informed about relevant vulnerabilities.
+
+A project can have one or more [notification channels](notifications.md), which define **how** notifications are delivered.
+
+OpenCVE currently supports:
+
+- `email` – send updates to configured addresses,
+- `slack` – post updates to Slack channels,
+- `webhook` – send updates via HTTP POST to external systems.
+
+Users can combine channels to fit their workflows. For example:
+
+- All updates can be sent to an API using a webhook,
+- Critical CVEs (CVSS >= 9) can trigger an email to a mailing list.
+
+![OpenCVE Notification](../images/opencve-notification.png){.center style="width:90%"}
+
+!!! note
+    Additional channels, such as `Microsoft Teams`, are planned for future releases.
+
+## Reports
+
+Each project includes a **Reports** tab, which provides a daily summary of all activity related to the project's subscriptions (the technologies you track).
+
+![OpenCVE Report](../images/opencve-report.png){.center style="width:90%"}
+
+Daily reports give users a complete overview of what happened with their tracked technologies, helping teams stay informed and maintain visibility over time.
+
+!!! info
+
+    Reports are different from notifications:
+
+    - **Notifications** alert you in real time when a CVE matches your filters,
+    - **Daily reports** include all CVE updates for your subscriptions, providing a broader view of activity.
+
+## AI-Powered Report Summary
+
+In addition to raw reports, OpenCVE generates an **AI-powered summary** for each project. This summary highlights:
+
+- the most critical CVEs,
+- priority areas,
+- recommended actions.
+
+It allows users to quickly understand where to focus, without manually reviewing every vulnerability.
+
+![Report Summary](../images/guides/report_summaries/report-summary.png){.center style="width:100%"}
+
+## Users
+
+Users are members of your organization who can collaborate within OpenCVE.
+
+Each user can:
+
+- **Access** projects to view CVEs, reports, and summaries relevant to their subscriptions.
+- **Collaborate** on vulnerability analysis, marking CVEs as reviewed, or sharing insights with the team.
+- **Be assigned** responsibilities such as analysis, remediation tracking, or risk acceptance.
+
+
+By assigning roles and responsibilities within projects, OpenCVE ensures **clear ownership** of vulnerabilities and **efficient collaboration** between security and engineering teams.
+
+## Subscriptions
+
+Subscriptions define the **technologies you monitor** for vulnerabilities, such as vendors, products, or software stacks (e.g., Fortinet, Cisco, WordPress, Terraform).
+
+Subscriptions allow teams to **prioritize** critical technologies, organize monitoring efficiently, and ensure consistent vulnerability tracking across all projects.

docs/kb.md → docs/concepts/kb.md

@@ -6,13 +6,13 @@ The Knowledge Base (KB) is at the core of how OpenCVE operates. It serves as a c
 
 The KB is hosted as a public GitHub repository at [https://github.com/opencve/opencve-kb](https://github.com/opencve/opencve-kb), so everyone can access it freely.
 
-![KB Commit](images/kb/commit.png){.center style="width:75%"}
+![KB Commit](../images/kb/commit.png){.center style="width:75%"}
 
 It is populated automatically by scripts that are not part of the public OpenCVE codebase. These scripts continuously pull data from the various providers, process it, and store the aggregated result in the KB.
 
 Then all OpenCVE instances fetch this KB to populate their own database. In the end, when you browse the web application, you browse the KB:
 
-![CVE-2024-45409](images/kb/cve-2024-45409.png){.center style="width:75%"}
+![CVE-2024-45409](../images/kb/cve-2024-45409.png){.center style="width:75%"}
 
 ## Objective
 
@@ -64,15 +64,15 @@ In some cases the CVE data may differ from provider to provider.
 
 For example, this is the case for the weaknesses of the [CVE-2023-5176](https://github.com/opencve/opencve-kb/blob/main/2023/CVE-2023-5176.json) CVE. The NVD assigned it the `CWE-787` weakness ([source](https://nvd.nist.gov/vuln/detail/CVE-2023-5176)):
 
-![NVD CVE-2023-5176 Weakness](images/kb/nvd_CVE-2023-5176_weakness.png){.center style="width:650px"}
+![NVD CVE-2023-5176 Weakness](../images/kb/nvd_CVE-2023-5176_weakness.png){.center style="width:650px"}
 
 While RedHat assigned the `CWE-120` weakness ([source](https://access.redhat.com/security/cve/CVE-2023-5176)):
 
-![Redhat CVE-2023-5176 Weakness](images/kb/redhat_CVE-2023-5176_weakness.png){.center style="width:550px"}
+![Redhat CVE-2023-5176 Weakness](../images/kb/redhat_CVE-2023-5176_weakness.png){.center style="width:550px"}
 
 In this case OpenCVE merged the weaknesses information in the KB ([source](https://github.com/opencve/opencve-kb/blob/a2fac4fab1dba59e2c44abfb19ca43d7fd63c595/2023/CVE-2023-5176.json#L190-L199)):
 
-![OpenCVE CVE-2023-5176 Weaknesses](images/kb/opencve_CVE-2023-5176_weaknesses.png){.center style="width:250px"}
+![OpenCVE CVE-2023-5176 Weaknesses](../images/kb/opencve_CVE-2023-5176_weaknesses.png){.center style="width:250px"}
 
 This approach allows OpenCVE to present users with a single, unified value for critical fields, while still benefiting from the diversity of its data sources.
 

docs/notifications.md → docs/concepts/notifications.md

@@ -10,7 +10,7 @@ OpenCVE then checks each project that has subscribed to these vendors and produc
 
 A project can have zero or multiple notifications.
 
-![OpenCVE Notifications List](images/opencve-notifications-list.png){.center style="width:100%"}
+![OpenCVE Notifications List](../images/opencve-notifications-list.png){.center style="width:100%"}
 
 ## Notification Filters
 
@@ -22,7 +22,7 @@ The user can also decide to be notified based on the type of modification: wheth
 
 This allows users to receive notifications only for the changes that matter to them. Furthermore, they can configure one notification to send high-severity CVEs to a channel that is closely monitored, while sending all other notifications to a less-watched channel.
 
-![OpenCVE Notification Filters](images/opencve-notification.png){.center style="width:100%"}
+![OpenCVE Notification Filters](../images/opencve-notification.png){.center style="width:100%"}
 
 ## Notification Types
 
@@ -35,11 +35,11 @@ This allows users to receive notifications only for the changes that matter to t
 
 This is the simplest type of notification. When a change is detected, an email is sent to the address configured in the settings.
 
-![OpenCVE Email Notification](images/opencve-email-notification-form.png){.center style="width:70%"}
+![OpenCVE Email Notification](../images/opencve-email-notification-form.png){.center style="width:70%"}
 
 Here is an example:
 
-![OpenCVE Email Notification](images/opencve-email-notification.png){.center style="width:100%"}
+![OpenCVE Email Notification](../images/opencve-email-notification.png){.center style="width:100%"}
 
 ### Slack
 
@@ -54,19 +54,19 @@ https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
 
 Simply provide this URL in the notification configuration to start receiving CVE updates in your chosen Slack channel:
 
-![OpenCVE Slack Notification](images/opencve-slack-notification-form.png){.center style="width:70%"}
+![OpenCVE Slack Notification](../images/opencve-slack-notification-form.png){.center style="width:70%"}
 
 Here is an example:
 
-![OpenCVE Slack Notification](images/opencve-slack-notification.png){.center style="width:100%"}
+![OpenCVE Slack Notification](../images/opencve-slack-notification.png){.center style="width:100%"}
 
 ### Webhook
 
 Webhook notifications allow users to interface with their own information systems or tools, such as an ITSM service.
 
 When a change is detected, a POST request is sent to the URL defined in the configuration. The user can also add custom headers if required by their system.
 
-![OpenCVE Webhook Notification](images/opencve-webhook-notification.png){.center style="width:75%"}
+![OpenCVE Webhook Notification](../images/opencve-webhook-notification.png){.center style="width:75%"}
 
 <details><summary>Click to show a payload example</summary>
 

docs/deployment.md

@@ -67,7 +67,7 @@ It will proceed with all the installation steps automatically. When all the step
 - on port 8080 for OpenCVE Airflow scheduler
  You can login with the username "xxx" and password "xxx".
 
- 👋 Installation complete! Thank you for choosing OpenCVE! 
+ 👋 Installation complete! Thank you for choosing OpenCVE!
 
 ```
 
@@ -184,7 +184,7 @@ Updating files: 100% (61734/61734), done.
 
 ### import-opencve-kb
 
-This command imports the [OpenCVE KB](kb.md) in your database:
+This command imports the [OpenCVE KB](concepts/kb.md) in your database:
 
 ```
 ./install.sh import-opencve-kb
@@ -258,7 +258,7 @@ This file exposes important settings used by the OpenCVE webserver:
 - `OPENCVE_DATABASE_URL`: the URI of the database. You need to update it if you have changed some of the postgresql parameters in the docker compose env file. The postgresql connection parameters need to be the same in both web and docker compose `.env` files.
 - `OPENCVE_SECRET_KEY`: this variable has to be replaced with a new secret when the web server is up the first time
 - `OPENCVE_*_REPO_PATH`: the paths of the repositories (KB, Mitre, NVD...)
-- `OPENCVE_V1_DATABASE`: the URI of an OpenCVE v1 instance (used for [data migration](../guides/migrate_opencve_v1))
+- `OPENCVE_V1_DATABASE`: the URI of an OpenCVE v1 instance (used for [data migration](guides/migrate_opencve_v1.md))
 
 
 **web/opencve/conf/settings.py**
@@ -274,7 +274,7 @@ This file is used to configure the Airflow scheduler of OpenCVE.
 You can check the list of Airflow configurations [here](https://airflow.apache.org/docs/apache-airflow/stable/configurations-ref.html) to customize your Airflow instance.
 
 !!! info
-    You can refer to this [dedicated guide](../guides/smtp_configuration) to configure SMTP settings and enable email sending.
+    You can refer to this [dedicated guide](guides/smtp_configuration.md) to configure SMTP settings and enable email sending.
 
 ## Upgrade
 

docs/guides/smtp_configuration.md

@@ -99,7 +99,7 @@ Repeat for confirmation:
 User "admin" created with role "Admin"
 ```
 
-Then access the Airflow UI in your browser (default port: **8080**, as per the [Deployment & Setup](../../deployment) guide) and trigger the `check_smtp` DAG:
+Then access the Airflow UI in your browser (default port: **8080**, as per the [Deployment & Setup](../deployment.md) guide) and trigger the `check_smtp` DAG:
 
 ![Trigger check-smtp DAG](../images/guides/smtp_configuration/trigger-check-smtp-dag.png){.center style="width:100%"}
 

mkdocs.yml

@@ -23,9 +23,9 @@ nav:
   - Home: 'index.md'
   - Deployment & Setup: 'deployment.md'
   - Concepts:
-      - Organizations & Projects: 'organizations_projects.md'
-      - Knowledge Base (KB): 'kb.md'
-      - Notifications: 'notifications.md'
+      - Core Concepts: 'concepts/core.md'
+      - Knowledge Base (KB): 'concepts/kb.md'
+      - Notifications: 'concepts/notifications.md'
   - Guides:
       - Advanced Search: 'guides/advanced_search.md'
       - Custom Dashboards: 'guides/custom_dashboards.md'