Skip to content

Commit b022ee1

Browse files
gildubgildub
committed
Architectural views
1 parent e07a0e8 commit b022ee1

File tree

5 files changed

+442
-22
lines changed

5 files changed

+442
-22
lines changed

‎docs/design/README.md‎

Lines changed: 215 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,234 @@
1-
# Using Marmaid Command Line to (re)generate images
1+
# Trustify Architecture Documentation
22

3-
Mermaid command line tool can be used export images out of Mermaid.
3+
This document provides an organized overview of Trustify's architecture from multiple perspectives. Each view serves a different purpose and audience.
44

5-
Detailed installation instructions are available on the Mermaid CLI repo, available at https://github.com/mermaid-js/mermaid-cli.
6-
Alternatively to avoid installing the Node stack dependencies on your machine, a pre-built Docker image is available to use, which is documented in the Mermaid GitHub repo too.
5+
## Quick Start Guide
76

8-
The following command ingests the Marmaid markup and generate the PNG (SVG, PDF also supported).
7+
**New to Trustify?** Start with the [Domain Model](domain-model.md) to understand business concepts, then review the [C4 Architecture](architecture.md) to see how components work together.
98

10-
```bash
11-
mmdc -i domain-model.mmd -o domain-model.png
9+
**Working on database changes?** Go directly to the [Data Model](data-model.md).
10+
11+
**Designing new features?** Use the [Domain Model](domain-model.md) for concepts and [C4 Architecture](architecture.md) for service boundaries.
12+
13+
## Architecture Views
14+
15+
Trustify's architecture is documented through three complementary views following industry-standard modeling approaches:
16+
17+
- **[Domain Model](domain-model.md)** - Business concepts and relationships
18+
- **Audience:** Product managers, domain experts, developers
19+
- **When to Use:** Understanding terminology, feature planning, API design
20+
21+
- **[C4 Architecture](architecture.md)** - System decomposition and component interactions
22+
- **Audience:** Architects, developers, DevOps
23+
- **When to Use:** System design, deployment planning, integration work
24+
25+
- **[Data Model](data-model.md)** - Physical database schema
26+
- **Audience:** DBAs, backend developers
27+
- **When to Use:** Database queries, migrations, schema changes
28+
29+
### Domain Model (Business View)
30+
31+
**Standard:** Domain-Driven Design (DDD) concepts
32+
[View Domain Model →](domain-model.md)
33+
34+
High-level business entities organized into logical domains:
35+
36+
- **Supply Chain Intelligence**: SBOM, Package, File, License
37+
- **Security Intelligence**: Advisory, Vulnerability, Weakness
38+
- **Product Management**: Organization, Product, ProductVersion
39+
- **Data Pipeline**: Importer, Ingestor, SourceDocument, Storage
40+
- **Analysis & Query**: Analysis Graph (DAG), Query Service
41+
42+
### C4 Architecture (System View)
43+
44+
**Standard:** C4 Model (Context, Container, Component, Code)
45+
[View C4 Architecture →](architecture.md)
46+
47+
Hierarchical view showing system decomposition at multiple zoom levels:
48+
49+
- **Level 1 - System Context**: External systems and users
50+
- **Level 2 - Container Diagram**: Runtime components and interactions
51+
- **Level 3 - Component Diagrams**: Internal structure of containers
52+
53+
### Data Model (Implementation View)
54+
55+
**Standard:** Entity-Relationship Diagram (ERD)
56+
[View Data Model →](data-model.md)
57+
58+
PostgreSQL database schema with 50+ tables:
59+
60+
- Primary keys (PK) and foreign keys (FK) explicitly marked
61+
- Cardinality shown with crow's foot notation
62+
- Data types specified for each column
63+
- Organized by domain
64+
65+
### Relationship Between Views
66+
67+
```mermaid
68+
graph LR
69+
A[Domain Model<br/>Business Concepts] -->|maps to| B[C4 Architecture<br/>System Components]
70+
B -->|implements| C[Data Model<br/>Database Schema]
71+
A -.->|informs| C
72+
73+
style A fill:#e1f5e1,stroke:#4caf50
74+
style B fill:#e1f0ff,stroke:#2196f3
75+
style C fill:#fff0e1,stroke:#ff9800
1276
```
1377

14-
### Note
78+
- **Domain Model → C4 Architecture**: Business entities map to services and components
79+
- **C4 Architecture → Data Model**: Services read/write database tables
80+
- **Domain Model → Data Model**: Conceptual entities normalize into database tables
81+
82+
---
83+
84+
## Key Architectural Concepts
85+
86+
### Two-Model Architecture
87+
88+
Trustify maintains two distinct graph representations:
89+
90+
1. **Logical Model** (Database): Preserves exact SBOM relationships with original directionality
91+
2. **Conceptual Model** (Analysis Graph): Normalized DAG view for efficient traversal queries
92+
93+
See [ADR-00002: Analysis Graph API](../adrs/00002-analysis-graph.md) for details.
94+
95+
### Modulith Structure
96+
97+
Services are organized into modules following a consistent pattern:
98+
99+
- `endpoints/` - HTTP API handlers
100+
- `model/` - Serializable data models
101+
- `service/` - Business logic layer
102+
- Tests co-located with implementation
103+
104+
See [modules/README.md](../../modules/README.md) for module conventions.
105+
106+
### PURL Hierarchy
107+
108+
Packages are identified using a three-tier PURL structure:
109+
110+
- **BasePurl**: type, namespace, name
111+
- **VersionedPurl**: adds version to BasePurl
112+
- **QualifiedPurl**: adds qualifiers (platform, arch, etc.)
113+
114+
This enables efficient deduplication and version range queries.
115+
116+
---
15117

16-
A markup file (md) can be provided too, in which case `mmdc` will extract all the Mermaid diagrams and save them in indivual image files.
17-
Each file will be suffixed with an incremental number, i.e domain-model-1.png, domain-model-2.png, etc.
118+
## Subsystem Design Documentation
18119

19-
## Defaults values in `mermaid.json`
120+
These documents provide deep dives into specific subsystems and design patterns:
20121

21-
In order to generate or regenerate consistent diagrams we can use a configuration file for Mermaid options such as `--theme`.
122+
### Core Subsystems
22123

23-
For example :
124+
| Document | Topics Covered |
125+
| ------------------------------------ | ----------------------------------------------------------------------- |
126+
| [**Importer System**](importer.md) | Configuration, scheduling, job execution, error handling |
127+
| [**SBOM Storage**](sbom.md) | Node types, graph structure, PURL/CPE resolution, cross-SBOM references |
128+
| [**Product Model**](products.md) | Product hierarchy, version ranges, SBOM associations, status tracking |
129+
| [**Labels System**](labels.md) | Flexible metadata, JSONB implementation, query patterns |
130+
| [**API Patterns**](fetch-service.md) | Head/Summary/Details DTOs, relationship traversal, pagination |
131+
132+
### Architecture Decision Records (ADRs)
133+
134+
ADRs document significant architectural decisions with context, rationale, and consequences:
135+
136+
- [**ADR-00001**: Graph Analytics](../adrs/00001-graph-analytics.md) - Foundation of graph-based analysis
137+
- [**ADR-00002**: Analysis Graph API](../adrs/00002-analysis-graph.md) - Logical vs conceptual model separation
138+
- [**ADR-00003**: External References](../adrs/00003-external-references.md) - Cross-SBOM reference handling
139+
- [**ADR-00004**: Advisory Scores](../adrs/00004-advisory-scores.md) - CVSS score management
140+
- [**ADR-00009**: Conservative PURL Garbage Collection](../adrs/00009-conservative-purl-garbage-collection.md) - Data retention strategy
141+
- [**ADR-00011**: CSAF Remediation](../adrs/00011-csaf-remediation.md) - Advisory remediation handling
142+
143+
[View all ADRs →](../adrs/)
144+
145+
ADRs are immutable once accepted. New decisions that supersede old ones reference the original ADR rather than modifying it.
146+
147+
## Module Structure
148+
149+
Trustify follows a **modulith architecture** where the codebase is organized into cohesive modules with clear boundaries, deployed as a single application.
150+
151+
**Module Layout Standard:**
152+
153+
Each module in `modules/` follows a consistent structure:
154+
155+
```
156+
modules/my_module/
157+
├── src/
158+
│ ├── endpoints/ # HTTP API handlers (Actix-web routes)
159+
│ ├── model/ # Serializable DTOs for API responses
160+
│ ├── service/ # Business logic layer
161+
│ └── lib.rs # Module entry point
162+
└── Cargo.toml
163+
```
164+
165+
**Key Principles:**
166+
167+
- **Endpoints**: Pure routing and HTTP concerns, thin handlers that delegate to services
168+
- **Models**: Data Transfer Objects (DTOs) with `serde` and `utoipa` annotations for API documentation
169+
- **Services**: Core business logic, accepts database connections, returns domain results
170+
- **Co-located Tests**: Tests live alongside implementation for better maintainability
171+
172+
**Benefits:**
173+
174+
- **Clear Boundaries**: Modules encapsulate related functionality
175+
- **Independent Testing**: Each module can be tested in isolation
176+
- **Flexible Deployment**: Could be extracted to separate services if needed
177+
- **Team Ownership**: Teams can own specific modules
178+
- **Reduced Coupling**: Explicit dependencies between modules
179+
180+
**Current Modules:**
181+
182+
- `fundamental/` - Core entities (Advisory, SBOM, PURL, Vulnerability, Product)
183+
- `ingestor/` - Document parsing and storage
184+
- `importer/` - Scheduled import management
185+
- `analysis/` - Dependency graph analysis
186+
- `storage/` - Storage backend abstraction
187+
- `graphql/` - GraphQL API alternative
188+
- `ui/` - Web interface
189+
- `user/` - User preferences management
190+
191+
[Learn more about module conventions →](../../modules/README.md)
192+
193+
## API Documentation
194+
195+
Trustify provides comprehensive OpenAPI 3.0 documentation for all REST endpoints, automatically generated from code annotations using `utoipa`.
196+
197+
[View OpenAPI Specification →](../../openapi.yaml)
198+
199+
The API follows REST principles with consistent patterns as documented in [API Patterns](fetch-service.md).
200+
201+
## Contributing to Documentation
202+
203+
### When to Update Documentation
204+
205+
- **Domain Model**: When adding new business entities or relationships
206+
- **C4 Architecture**: When adding services, changing interactions, or deployment
207+
- **Data Model**: After migrations that add/modify tables
208+
- **Keep views in sync** to maintain documentation quality
209+
210+
### Generating Diagram Images
211+
212+
#### Using Mermaid CLI
213+
214+
Install from https://github.com/mermaid-js/mermaid-cli or use the pre-built Docker image.
215+
216+
**Basic command:**
24217

25218
```bash
26-
mmdc -c mermaid.json -i domain-model.md -o domain-model.png
219+
mmdc -i domain-model.md -o domain-model.png
27220
```
28221

29-
## Data model options
222+
**With configuration:**
30223

31-
The data model being large, the following was used to generate a readable image :
224+
```bash
225+
mmdc -c mermaid.json -i domain-model.md -o domain-model.png
226+
```
227+
228+
**For large diagrams (data model):**
32229

33230
```bash
34231
mmdc -c mermaid.json -i data-model.md -o data-model.png --width 1200 --height 1600 --scale 6
35232
```
233+
234+
**Note:** When providing a markdown file, `mmdc` extracts all Mermaid diagrams and saves them as individual files with incremental suffixes (e.g., `domain-model-1.png`, `domain-model-2.png`).

0 commit comments

Comments
 (0)