Mapping source code to software architecture using embedding models: Insights from an analysis of data properties

Context: Maintaining alignment between software architecture and organisational goals is vital for efficiency and cost control during refactoring. Manual reassignment of many fine-grained code entities to target modules is labor-intensive when only heterogeneous textual documentation is available. Objectives: Provide an operational assessment of an embedding-based approach for mapping source code snippets to architectural modules and identify, in this setting, the textual data properties that most clearly condition classification performance. Method: A classification pipeline is applied to six diverse software systems. We classify both functions and whole files under multiple documentation granularities and relate macro F1 variability to four primary properties: class separability/density, lexical (vocabulary) overlap, class balance, and similarity of data distributions between training and test sets. Results: Performance varies markedly across systems and datasets; file-level entities generally outperform functions. In our experiments, classification gains align most consistently with higher class separability/density in the embedding space, while lexical overlap and class balance show weaker, granularity-dependent effects. Added textual granularity can aid function-level mapping when it improves separability and overlap, but may introduce noise for files. Conclusions: In the evaluated pipeline, embedding-based mapping most effectively streamlines early refactoring when documentation yields sufficient lexical overlap and separable, dense class regions. Practitioners using similar embedding-based approaches should estimate overlap and separability early; if both are low, our results suggest preferring file-level granularity or enriching descriptions before pursuing fine-grained (function) mapping.