docs: add standardized comments to all services (Python, Go, Bash)

- Add docs/commenting-standard.md defining per-language comment standards
  (Go godoc, Python PEP-257, C Doxygen, Bash header blocks, SQL banners)

- services/dashboard: 100% docstring coverage (100/100 functions)
  - All FastAPI route handlers, helpers, classes, and models documented
  - Language: French (project convention)

- services/bot-detector: 100% docstring coverage (53/53 symbols)
  - bot_detector.py: 14 functions + module docstring
  - anubis/fetch_rules.py: 9 functions

- shared/python/ja4_common: full docstrings on ClickHouseClient (7 methods)
  and ClickHouseSettings class

- services/correlator: 24 godoc comments added across 6 Go files
  - correlation_service.go: 10 private helpers
  - unixsocket/source.go: 6 parsing/socket helpers
  - correlated_log.go: 4 field extraction helpers
  - orchestrator.go, logger.go, main.go: 4 comments

- services/correlator/scripts/audit-architecture.sh: standardized header block

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

services/correlator/internal/adapters/inbound/unixsocket/source.go

@@ -117,6 +117,7 @@ func (s *UnixSocketSource) Start(ctx context.Context, eventChan chan<- *domain.N
 	return nil
 }
 
+// readDatagrams lit en continu les datagrammes sur la socket Unix et envoie les événements normalisés sur le canal.
 func (s *UnixSocketSource) readDatagrams(ctx context.Context, eventChan chan<- *domain.NormalizedEvent) {
 	buf := make([]byte, MaxDatagramSize)
 
@@ -176,6 +177,7 @@ func (s *UnixSocketSource) readDatagrams(ctx context.Context, eventChan chan<- *
 	}
 }
 
+// resolveSource détermine la source d'un événement à partir du type déclaré ou de la présence d'en-têtes HTTP.
 func resolveSource(sourceType string, headers map[string]string) domain.EventSource {
 	switch strings.ToLower(strings.TrimSpace(sourceType)) {
 	case "a", "apache", "http":
@@ -191,6 +193,7 @@ func resolveSource(sourceType string, headers map[string]string) domain.EventSou
 	}
 }
 
+// parseJSONEvent désérialise un datagramme JSON et construit un NormalizedEvent validé avec ses champs obligatoires.
 func parseJSONEvent(data []byte, sourceType string) (*domain.NormalizedEvent, error) {
 	var raw map[string]any
 	if err := json.Unmarshal(data, &raw); err != nil {
@@ -298,6 +301,7 @@ func parseJSONEvent(data []byte, sourceType string) (*domain.NormalizedEvent, er
 	return event, nil
 }
 
+// getString extrait la valeur d'une clé sous forme de chaîne depuis une map JSON désérialisée.
 func getString(m map[string]any, key string) (string, bool) {
 	if v, ok := m[key]; ok {
 		if s, ok := v.(string); ok {
@@ -307,6 +311,7 @@ func getString(m map[string]any, key string) (string, bool) {
 	return "", false
 }
 
+// getInt extrait la valeur d'une clé sous forme d'entier depuis une map JSON en gérant les conversions de types courants.
 func getInt(m map[string]any, key string) (int, bool) {
 	if v, ok := m[key]; ok {
 		switch val := v.(type) {
@@ -328,6 +333,7 @@ func getInt(m map[string]any, key string) (int, bool) {
 	return 0, false
 }
 
+// getInt64 extrait la valeur d'une clé sous forme d'entier 64 bits depuis une map JSON en gérant les conversions de types courants.
 func getInt64(m map[string]any, key string) (int64, bool) {
 	if v, ok := m[key]; ok {
 		switch val := v.(type) {

services/correlator/internal/app/orchestrator.go

@@ -103,6 +103,7 @@ func (o *Orchestrator) Start() error {
 	return nil
 }
 
+// processEvents lit les événements du canal, les soumet au service de corrélation et écrit les résultats dans le puits.
 func (o *Orchestrator) processEvents(eventChan <-chan *domain.NormalizedEvent) {
 	for {
 		select {

services/correlator/internal/domain/correlated_log.go

@@ -101,6 +101,7 @@ func NewCorrelatedLog(apacheEvent, networkEvent *NormalizedEvent) CorrelatedLog
 	}
 }
 
+// extractFields copie l'ensemble des champs bruts d'un événement dans une nouvelle map.
 func extractFields(e *NormalizedEvent) map[string]any {
 	result := make(map[string]any)
 	for k, v := range e.Raw {
@@ -109,6 +110,7 @@ func extractFields(e *NormalizedEvent) map[string]any {
 	return result
 }
 
+// mergeFields fusionne les champs bruts de deux événements en préfixant les clés en collision par "a_" et "b_".
 func mergeFields(a, b *NormalizedEvent) map[string]any {
 	result := make(map[string]any)
 
@@ -136,6 +138,7 @@ func mergeFields(a, b *NormalizedEvent) map[string]any {
 	return result
 }
 
+// coalesceString retourne la première chaîne non vide parmi les deux arguments.
 func coalesceString(a, b string) string {
 	if a != "" {
 		return a
@@ -143,6 +146,7 @@ func coalesceString(a, b string) string {
 	return b
 }
 
+// coalesceInt retourne le premier entier non nul parmi les deux arguments.
 func coalesceInt(a, b int) int {
 	if a != 0 {
 		return a

services/correlator/internal/domain/correlation_service.go

@@ -74,6 +74,7 @@ type eventBuffer struct {
 	events *list.List
 }
 
+// newEventBuffer crée un nouveau tampon d'événements vide basé sur une liste doublement chaînée.
 func newEventBuffer() *eventBuffer {
 	return &eventBuffer{
 		events: list.New(),
@@ -288,6 +289,7 @@ func (s *CorrelationService) ProcessEvent(event *NormalizedEvent) []CorrelatedLo
 	return results
 }
 
+// getBufferSize retourne la taille actuelle du tampon correspondant à la source donnée.
 func (s *CorrelationService) getBufferSize(source EventSource) int {
 	switch source {
 	case SourceA:
@@ -298,6 +300,7 @@ func (s *CorrelationService) getBufferSize(source EventSource) int {
 	return 0
 }
 
+// isBufferFull vérifie si le tampon de la source donnée a atteint sa capacité maximale.
 func (s *CorrelationService) isBufferFull(source EventSource) bool {
 	switch source {
 	case SourceA:
@@ -355,6 +358,7 @@ func (s *CorrelationService) rotateOldestB() {
 	delete(s.networkTTLs, elem)
 }
 
+// processSourceA traite un événement de source A (HTTP/Apache) et retourne les journaux corrélés ou les place en attente d'orphelins.
 func (s *CorrelationService) processSourceA(event *NormalizedEvent) ([]CorrelatedLog, bool) {
 	key := event.CorrelationKey()
 	// Assign Keep-Alive sequence number (1-based) for this connection
@@ -457,6 +461,7 @@ func (s *CorrelationService) processSourceA(event *NormalizedEvent) ([]Correlate
 	return nil, true
 }
 
+// processSourceB traite un événement de source B (réseau) et retourne les journaux corrélés si une correspondance est trouvée.
 func (s *CorrelationService) processSourceB(event *NormalizedEvent) ([]CorrelatedLog, bool) {
 	key := event.CorrelationKey()
 	s.logger.Debugf("processing B event: key=%s timestamp=%v", key, event.Timestamp)
@@ -511,6 +516,7 @@ func (s *CorrelationService) processSourceB(event *NormalizedEvent) ([]Correlate
 	return nil, true
 }
 
+// eventsMatch vérifie si deux événements se trouvent dans la fenêtre temporelle de corrélation configurée.
 func (s *CorrelationService) eventsMatch(a, b *NormalizedEvent) bool {
 	diff := a.Timestamp.Sub(b.Timestamp)
 	if diff < 0 {
@@ -536,6 +542,7 @@ func (s *CorrelationService) bEventHasValidTTL(bEvent *NormalizedEvent) bool {
 	return false
 }
 
+// addEvent ajoute un événement au tampon correspondant à sa source et initialise son TTL réseau si nécessaire.
 func (s *CorrelationService) addEvent(event *NormalizedEvent) {
 	key := event.CorrelationKey()
 
@@ -551,6 +558,7 @@ func (s *CorrelationService) addEvent(event *NormalizedEvent) {
 	}
 }
 
+// cleanExpired supprime les événements expirés des tampons et retourne les orphelins forcés par l'expiration du TTL réseau.
 func (s *CorrelationService) cleanExpired() []CorrelatedLog {
 	// Clean expired B events first - use TTL map only (not event timestamp)
 	// This is critical for Keep-Alive: TTL is reset on each correlation,
@@ -693,6 +701,7 @@ func (s *CorrelationService) cleanNetworkBufferByTTL() []CorrelatedLog {
 	return forced
 }
 
+// findAndPopFirstMatch recherche et supprime le premier événement satisfaisant le critère dans le tampon.
 func (s *CorrelationService) findAndPopFirstMatch(
 	buffer *eventBuffer,
 	pending map[string][]*list.Element,
@@ -908,6 +917,7 @@ func (s *CorrelationService) EmitPendingOrphans() []CorrelatedLog {
 	return s.emitPendingOrphans()
 }
 
+// removeElementFromSlice retire l'élément ciblé d'une tranche de list.Element sans modifier l'ordre.
 func removeElementFromSlice(elements []*list.Element, target *list.Element) []*list.Element {
 	if len(elements) == 0 {
 		return elements

services/correlator/internal/observability/logger.go

@@ -4,8 +4,10 @@ package observability
 
 import jalogger "github.com/antitbone/ja4/ja4common/logger"
 
-// Type aliases — all existing correlator code compiles unchanged.
+// Logger est un alias du type Logger de ja4common pour la journalisation structurée.
 type Logger = jalogger.Logger
+
+// LogLevel est un alias du type LogLevel de ja4common pour le niveau de journalisation.
 type LogLevel = jalogger.LogLevel
 
 const (