Proposal: Contributor Architecture Overview Documentation

[Charanbhogavalli]

Hello maintainers,

While exploring the project structure (CLI, Engine, analyzers, and vulnerability matching flow), I noticed that new contributors may find it challenging to understand the internal architecture and data flow.

I would like to propose contributing a concise "Architecture Overview for Contributors" document explaining:

• High-level architecture (CLI → Engine → Analyzers → NVD matching → Report generation)
• How dependencies are identified and analyzed
• How vulnerability matching works (CPE, version ranges, CVSS threshold logic)
• Suggested entry points for new contributors

Before starting, I would like to confirm whether:

1. Such documentation already exists but I may have missed it, or
2. The maintainers would welcome this addition (e.g., in docs/ or Wiki).

I would be happy to align with any preferred structure or guidelines.

Thank you.

[Charanbhogavalli]

Thank you for adding the documentation label.

I will begin drafting a contributor-focused architecture overview covering:

High-level scan flow (CLI → Engine → Analyzers → CVE matching → Reports)

Key terminology (CPE, CVE, version ranges, CVSS threshold logic)

Common analyzer categories

Suggested entry points for new contributors

I will open a draft PR shortly for feedback before finalizing structure and placement.

[chadlwilson]

A label is not feedback on your proposal and I'm just a triager/contributor, not a maintainer. You said you wanted feedback before starting?

If you are an AI agent, or the output from an LLM, or will entirely be producing using an LLM - please disclose?

[jeremylong]

The older, slightly unmaintained wiki has a lot of the information you are likely looking to document.

[Charanbhogavalli]

Thank you for the feedback.
I’m new to contributing to larger open source projects and I realize I may have approached this the wrong way. My intention was to help improve onboarding for new contributors, but I understand that I should first ensure I’m aligned with existing documentation and project expectations.
I would appreciate guidance on what types of contributions are most appropriate for beginners in this repository. I’m genuinely interested in learning the codebase properly and contributing in a way that adds real value.
If there are specific areas (documentation updates, small bugs, analyzer improvements, test coverage, etc.) that are better starting points, I’d be grateful for direction.

[jeremylong]

I think the best would be to take some of the content from the wiki, update/expand it, and move it to the currently maintained maven site.