# hangin6639-arch/brand_alignment_project architecture

> Architecture diagram of the GitHub repository hangin6639-arch/brand_alignment_project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hangin6639-arch/brand_alignment_project
- Repository: https://github.com/hangin6639-arch/brand_alignment_project

## Overview

1. **Repository purpose**
   - This is an offline NLP analysis project for comparing **Contec’s intended brand identity** with **how the market and media portray the company**.
   - It is not a web app or service; the architecture is a **batch analytics pipeline** built from standalone Python scripts.

2. **Top-level architecture**
   - The repo is organized into three main zones:
     - **Data acquisition**: crawls and stores raw news text.
     - **Analysis**: cleans text, extracts entities, builds semantic/graph features, and computes brand gaps.
     - **Artifacts/outputs**: CSVs and charts that capture intermediate and final results.
   - The `data/`, `crawler/data/`, and `outputs/` folders show that the pipeline is designed around persisted files rather than a database.

3. **External data sources and boundaries**
   - The project pulls from two major source types:
     - **Market/media data**: Naver News articles collected by the crawler.
     - **Identity data**: the company’s official materials, including a **business report PDF** in `data/` and likely website/IR/newsroom text used by the analysis scripts.
   - These source boundaries map directly to the README’s 3-layer model:
     - Internal Identity
     - Curated Image
     - Raw Market Image

4. **Crawler subsystem**
   - `crawler/naver_news_crawler.py` is the ingestion component.
   - It appears to harvest news articles and write them to `crawler/data/raw_articles.csv` and `data/raw_articles.csv`.
   - `crawler/query_strategy.md` suggests the query design is part of the data collection strategy, which matters because the quality of downstream semantic analysis depends on the retrieval scope.
   - `crawler.log` files indicate the crawler is run as an operational batch job with logs, not as an interactive component.

5. **Text parsing and data cleanup**
   - `test_parser.py`, `test_parser_v2.py`, `debug_search_page.html`, and the analysis scripts imply a parsing/debugging boundary around HTML or PDF extraction.
   - The repo separates raw ingestion from normalized text creation, which is important for architecture diagrams: **raw source → parsed text → curated corpus**.
   - The presence of `outputs/purified_articles_sample.csv`, `phase3_purified_sample.csv`, `phase4_restored_space.csv`, and `phase5_normalized_space.csv` shows staged text normalization rather than one monolithic cleaning step.

6. **Core semantic analysis layer**
   - The main NLP stack is centered on `sentence-transformers` with the Korean SBERT model `snunlp/KR-SBERT-V40K-klueNLI-augSTS`.
   - `analysis/sbert_analysis.py`, `analysis/brand_alignment.py`, `analysis/brand_gap_analyzer.py`, and the top-level `brand_gap_analyzer_v2.py` form the semantic comparison layer.
   - This layer converts text corpora into embeddings and computes similarity/gap metrics across the three brand layers.

7. **Identity and corpus construction**
   - `analysis/contec_identity_builder.py` likely builds the company’s internal identity corpus from official materials.
   - `outputs/identity/contec_brand_corpus.csv` shows the result of this step: a structured brand corpus used as the “anchor” for later comparisons.
   - This is a key boundary in the system: the identity corpus is not just another news set; it is the controlled reference against which external perception is measured.

8. **Market-language and keyword analysis**
   - `analysis/tfidf_analysis.py` and `outputs/tfidf_top_keywords.csv` indicate a lexical layer used to summarize dominant terms and themes.
   - This is complementary to the semantic embeddings: TF-IDF provides interpretable keyword signals, while SBERT handles meaning-level comparison.
   - `analysis/brand_alignment.py` likely connects these lexical and semantic views to measure how aligned different content layers are.

9. **Entity and network analysis subsystem**
   - `analysis/space_network_analysis.py` and `outputs/network/network_centrality_metrics.csv` indicate a graph-based view of the market.
   - The project extracts entities such as companies, policies, technologies, regions, and investment terms, then maps relationships between them.
   - This subsystem is distinct from the brand-gap calculation: it explains the **surrounding industrial context** and helps interpret the market narrative network.

10. **Research framing and analysis orchestration**
   - `analysis/research_questions.md` shows the project is driven by explicit analytical questions rather than generic model training.
   - `analysis/abvp_analysis.py`, `analysis/brand_communication_flow.py`, and `analysis/brand_gap_analyzer.py` suggest a staged analytical workflow:
     - identify identity
     - observe communication flow
     - measure semantic drift/gap
   - `analysis/brand_communication_flow.py` appears to model the transmission path from identity through PR to market perception.

11. **Outputs and intermediate artifacts**
   - The `outputs/` tree stores the pipeline’s deliverables:
     - `brand_alignment_results.csv`
     - `identity/contec_brand_corpus.csv`
     - `network/network_centrality_metrics.csv`
     - `tfidf_top_keywords.csv`
     - phase-sliced CSVs for cleaned and normalized article sets
   - The architecture is therefore **artifact-driven**: each phase emits a file that becomes the next phase’s input or a final reportable result.

12. **Operational characteristics**
   - This repo is designed for reproducible offline analysis using Python, `pandas`, `numpy`, `scikit-learn`, `networkx`, `matplotlib`, `beautifulsoup4`, and `sentence-transformers`.
   - There is no evidence of a service layer, API server, or database; the main runtime boundary is the local filesystem plus the Python environment defined in `requirements.txt`.
   - For an architecture diagram, the clearest shape is: **Crawler → Raw CSVs → Cleaning/Parsing → Identity & Market Corpora → Embedding/TF-IDF/Graph analysis → CSV/PNG outputs**.

Main entry points: [`outputs/phase5_normalized_space.csv`](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/phase5_normalized_space.csv) (Phase samples), [`analysis/brand_alignment.py`](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/brand_alignment.py) (Brand alignment), [`analysis/brand_gap_analyzer.py`](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/brand_gap_analyzer.py) (Gap analyzer), [`crawler/naver_news_crawler.py`](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/crawler/naver_news_crawler.py) (News crawler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_acquisition["Data acquisition"]
  node_node_crawler["News crawler<br/>batch ingestion"]
  node_node_query_strategy["Query strategy<br/>collection plan<br/>[query_strategy.md]"]
  node_node_raw_articles_crawler[("Crawler CSV<br/>raw corpus<br/>[raw_articles.csv]")]
  node_node_raw_articles_root[("Raw articles<br/>raw corpus<br/>[raw_articles.csv]")]
  node_node_business_report["Business report<br/>official source"]
end

subgraph group_group_analysis["Analysis"]
  node_node_parser["Parser tests<br/>extraction debug<br/>[test_parser.py]"]
  node_node_parser_v2["Parser v2<br/>extraction debug<br/>[test_parser_v2.py]"]
  node_node_identity_builder["Identity builder<br/>corpus builder"]
  node_node_sbert["SBERT analysis<br/>embedding layer<br/>[sbert_analysis.py]"]
  node_node_brand_alignment["Brand alignment<br/>semantic compare<br/>[brand_alignment.py]"]
  node_node_brand_gap["Gap analyzer<br/>drift metrics"]
  node_node_brand_gap_v2["Gap analyzer v2<br/>orchestrator"]
  node_node_communication_flow["Comm flow<br/>narrative flow"]
  node_node_abvp["ABVP analysis<br/>framework analysis<br/>[abvp_analysis.py]"]
  node_node_tfidf["TF-IDF<br/>lexical analysis<br/>[tfidf_analysis.py]"]
  node_node_network["Space network<br/>graph analysis"]
  node_node_questions["Research questions<br/>study framing"]
end

subgraph group_group_outputs["Outputs"]
  node_node_alignment_results[("Alignment results<br/>final metrics")]
  node_node_identity_corpus[("Identity corpus<br/>structured corpus")]
  node_node_network_metrics[("Network metrics<br/>graph metrics")]
  node_node_tfidf_keywords[("Top keywords<br/>keyword summary")]
  node_node_phase_samples[("Phase samples<br/>cleaned corpus")]
end

node_node_query_strategy -->|"guides crawl"| node_node_crawler
node_node_crawler -->|"writes"| node_node_raw_articles_crawler
node_node_crawler -->|"publishes"| node_node_raw_articles_root
node_node_business_report -->|"feeds"| node_node_identity_builder
node_node_raw_articles_root -->|"parses"| node_node_parser
node_node_parser -->|"refines"| node_node_parser_v2
node_node_parser_v2 -->|"normalizes"| node_node_phase_samples
node_node_phase_samples -->|"supports"| node_node_identity_builder
node_node_identity_builder -->|"exports"| node_node_identity_corpus
node_node_identity_corpus -->|"embeds"| node_node_sbert
node_node_phase_samples -->|"embeds"| node_node_sbert
node_node_sbert -->|"compares"| node_node_brand_alignment
node_node_brand_alignment -->|"exports"| node_node_alignment_results
node_node_brand_alignment -->|"extends"| node_node_brand_gap
node_node_brand_gap -->|"orchestrated by"| node_node_brand_gap_v2
node_node_brand_gap -->|"interprets"| node_node_communication_flow
node_node_abvp -->|"frames"| node_node_brand_gap
node_node_phase_samples -->|"summarizes"| node_node_tfidf
node_node_tfidf -->|"exports"| node_node_tfidf_keywords
node_node_phase_samples -->|"analyzes"| node_node_network
node_node_network -->|"exports"| node_node_network_metrics
node_node_questions -->|"drives"| node_node_abvp
node_node_questions -->|"drives"| node_node_brand_alignment

click node_node_crawler "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/crawler/naver_news_crawler.py"
click node_node_query_strategy "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/crawler/query_strategy.md"
click node_node_raw_articles_crawler "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/crawler/data/raw_articles.csv"
click node_node_raw_articles_root "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/data/raw_articles.csv"
click node_node_business_report "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/data/[컨텍]사업보고서(2026.03.23).pdf"
click node_node_parser "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/test_parser.py"
click node_node_parser_v2 "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/test_parser_v2.py"
click node_node_identity_builder "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/contec_identity_builder.py"
click node_node_sbert "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/sbert_analysis.py"
click node_node_brand_alignment "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/brand_alignment.py"
click node_node_brand_gap "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/brand_gap_analyzer.py"
click node_node_brand_gap_v2 "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/brand_gap_analyzer_v2.py"
click node_node_communication_flow "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/brand_communication_flow.py"
click node_node_abvp "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/abvp_analysis.py"
click node_node_tfidf "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/tfidf_analysis.py"
click node_node_network "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/space_network_analysis.py"
click node_node_questions "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/research_questions.md"
click node_node_alignment_results "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/brand_alignment_results.csv"
click node_node_identity_corpus "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/identity/contec_brand_corpus.csv"
click node_node_network_metrics "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/network/network_centrality_metrics.csv"
click node_node_tfidf_keywords "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/tfidf_top_keywords.csv"
click node_node_phase_samples "https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/phase5_normalized_space.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_crawler,node_node_query_strategy,node_node_raw_articles_crawler,node_node_raw_articles_root,node_node_business_report toneBlue
class node_node_parser,node_node_parser_v2,node_node_identity_builder,node_node_sbert,node_node_brand_alignment,node_node_brand_gap,node_node_brand_gap_v2,node_node_communication_flow,node_node_abvp,node_node_tfidf,node_node_network,node_node_questions toneAmber
class node_node_alignment_results,node_node_identity_corpus,node_node_network_metrics,node_node_tfidf_keywords,node_node_phase_samples toneMint
```

## Components

### Data acquisition

Batch crawling and raw article capture from Naver News plus source documents for identity analysis.

- [News crawler](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/crawler/naver_news_crawler.py): batch ingestion · Harvests Naver News articles and writes raw article CSVs for downstream processing. · `crawler/naver_news_crawler.py`
- [Query strategy](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/crawler/query_strategy.md): collection plan · Defines or documents the search scope and retrieval approach for news collection. · `crawler/query_strategy.md`
- [Crawler CSV](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/crawler/data/raw_articles.csv): raw corpus · Crawler output stored under the crawler workspace. · `crawler/data/raw_articles.csv`
- [Raw articles](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/data/raw_articles.csv): raw corpus · Shared raw article store used as input to analysis scripts. · `data/raw_articles.csv`
- [Business report](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/data/[컨텍]사업보고서(2026.03.23).pdf): official source · Official company report PDF used as part of the internal identity corpus. · `data/[컨텍]사업보고서(2026.03.23).pdf`

### Analysis

Text cleaning, identity corpus building, semantic comparison, keyword extraction, and network analysis.

- [Parser tests](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/test_parser.py): extraction debug · HTML/PDF parsing and normalization boundary used to validate text extraction behavior. · `test_parser.py`
- [Parser v2](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/test_parser_v2.py): extraction debug · Second parser iteration for handling extraction and cleanup edge cases. · `test_parser_v2.py`
- [Identity builder](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/contec_identity_builder.py): corpus builder · Builds the controlled internal identity corpus from official materials. · `analysis/contec_identity_builder.py`
- [SBERT analysis](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/sbert_analysis.py): embedding layer · Computes semantic embeddings using sentence-transformers for content comparison. · `analysis/sbert_analysis.py`
- [Brand alignment](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/brand_alignment.py): semantic compare · Connects identity and market corpora to measure alignment and semantic distance. · `analysis/brand_alignment.py`
- [Gap analyzer](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/brand_gap_analyzer.py): drift metrics · Calculates brand gap and semantic drift across identity, curated image, and market image layers. · `analysis/brand_gap_analyzer.py`
- [Gap analyzer v2](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/brand_gap_analyzer_v2.py): orchestrator · Top-level script variant that runs or refines the brand gap workflow. · `brand_gap_analyzer_v2.py`
- [Comm flow](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/brand_communication_flow.py): narrative flow · Models how identity is transmitted through communication and perceived in the market. · `analysis/brand_communication_flow.py`
- [ABVP analysis](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/abvp_analysis.py): framework analysis · Stage-specific analytical logic for brand/value/positioning interpretation. · `analysis/abvp_analysis.py`
- [TF-IDF](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/tfidf_analysis.py): lexical analysis · Extracts interpretable keyword signals and dominant themes from the corpus. · `analysis/tfidf_analysis.py`
- [Space network](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/space_network_analysis.py): graph analysis · Builds entity relationship networks to explain the surrounding industrial context. · `analysis/space_network_analysis.py`
- [Research questions](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/analysis/research_questions.md): study framing · Defines the analytical questions driving the offline comparison workflow. · `analysis/research_questions.md`

### Outputs

Persisted CSV artifacts used as intermediate inputs and final results for the offline pipeline.

- [Alignment results](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/brand_alignment_results.csv): final metrics · Primary CSV output for semantic brand alignment comparisons. · `outputs/brand_alignment_results.csv`
- [Identity corpus](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/identity/contec_brand_corpus.csv): structured corpus · Structured brand corpus representing internal identity as the anchor reference. · `outputs/identity/contec_brand_corpus.csv`
- [Network metrics](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/network/network_centrality_metrics.csv): graph metrics · Centrality and related metrics derived from entity network analysis. · `outputs/network/network_centrality_metrics.csv`
- [Top keywords](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/tfidf_top_keywords.csv): keyword summary · CSV summary of salient terms from lexical analysis. · `outputs/tfidf_top_keywords.csv`
- [Phase samples](https://github.com/hangin6639-arch/brand_alignment_project/blob/main/outputs/phase5_normalized_space.csv): cleaned corpus · Staged purified and normalized article samples that represent the text cleanup pipeline. · `outputs/phase5_normalized_space.csv`

## Connections

- Query strategy → News crawler: guides crawl · The query plan shapes which news articles are collected.
- News crawler → Crawler CSV: writes · Crawler persists raw article captures in its own data area.
- News crawler → Raw articles: publishes · Collected articles are also stored in the shared raw data folder.
- Business report → Identity builder: feeds · Official report content contributes to the internal identity corpus.
- Raw articles → Parser tests: parses · Raw articles enter the text extraction and cleanup boundary.
- Parser tests → Parser v2: refines · Second parser iteration handles extraction edge cases and normalization.
- Parser v2 → Phase samples: normalizes · Outputs staged cleaned article samples for later analysis.
- Phase samples → Identity builder: supports · Normalized text helps construct the controlled identity and comparison corpora.
- Identity builder → Identity corpus: exports · Builder emits the structured identity corpus artifact.
- Identity corpus → SBERT analysis: embeds · Identity corpus is vectorized for semantic analysis.
- Phase samples → SBERT analysis: embeds · Cleaned market text is encoded into semantic vectors.
- SBERT analysis → Brand alignment: compares · Embedding space is used to measure identity versus market alignment.
- Brand alignment → Alignment results: exports · Alignment metrics are written as final CSV results.
- Brand alignment → Gap analyzer: extends · Semantic alignment feeds the explicit brand gap calculation.
- Gap analyzer → Gap analyzer v2: orchestrated by · Top-level runner coordinates or reuses the gap analysis workflow.
- Gap analyzer → Comm flow: interprets · Gap analysis is contextualized through communication flow modeling.
- ABVP analysis → Gap analyzer: frames · ABVP-style interpretation supports the gap measurement stage.
- Phase samples → TF-IDF: summarizes · Clean corpus is reduced to interpretable keyword signals.
- TF-IDF → Top keywords: exports · Top terms are persisted as a CSV artifact.
- Phase samples → Space network: analyzes · Entity-rich text is used to build the market relationship network.
- Space network → Network metrics: exports · Network centrality and related metrics are stored for reporting.
- Research questions → ABVP analysis: drives · Research questions provide the analytical framing for the workflow.
- Research questions → Brand alignment: drives · Questions also shape the semantic comparison stage.
