Contact extraction utilities

graph TB
subgraph "Python Backend"
EC[extract_contacts.py<br/>Main contact extraction utilities]
APP[app.py<br/>Web API service]
PMN[parse_manual_numbers.py<br/>Manual number parsing]
VN[validate_number.py<br/>Phone number validation]
RT[requirements.txt<br/>Dependencies]
end
subgraph "Local Prototypes"
BP[beta_pandas.py<br/>Pandas integration examples]
CF[cli_functions.py<br/>CLI functionality]
end
subgraph "Supported File Formats"
CSV[CSV Files]
XLS[XLS/XLSX Files]
TXT[Plain Text Files]
end
EC --> CSV
EC --> XLS
EC --> TXT
APP --> EC
PMN --> VN
BP --> CSV
BP --> XLS

sequenceDiagram
participant Client as "Client Application"
participant API as "Flask API"
participant Parser as "Contact Parser"
participant Cleaner as "Phone Cleaner"
participant FileHandler as "File Handler"
Client->>API : POST /upload (multipart/form-data)
API->>API : Validate file type & size
API->>FileHandler : Save uploaded file
API->>Parser : Extract contacts from file
Parser->>Parser : Detect file format
Parser->>FileHandler : Read file content
Parser->>Cleaner : Clean phone numbers
Cleaner-->>Parser : Standardized numbers
Parser-->>API : Processed contacts
API->>FileHandler : Cleanup temporary file
API-->>Client : JSON response with contacts
Note over Client,Cleaner : Error handling throughout process

flowchart TD
Start([CSV Processing Start]) --> ReadHeaders["Read CSV Headers"]
ReadHeaders --> DetectPhoneCols["Detect Phone Number Columns"]
DetectPhoneCols --> CheckKeywords{"Contains<br/>phone,number,mobile,cell,tel?"}
CheckKeywords --> |Yes| AddToPhone["Add to Phone Columns"]
CheckKeywords --> |No| CheckNameCols["Check Name Columns"]
CheckNameCols --> CheckNameKeywords{"Contains<br/>name,contact,person?"}
CheckNameKeywords --> |Yes| AddToName["Add to Name Columns"]
CheckNameKeywords --> |No| NextCol["Next Column"]
AddToPhone --> NextCol
AddToName --> NextCol
NextCol --> MoreCols{"More Columns?"}
MoreCols --> |Yes| DetectPhoneCols
MoreCols --> |No| SelectColumns["Select Final Columns"]
SelectColumns --> UseFirstPhone["Use First Phone Column<br/>or First Column"]
UseFirstPhone --> UseSecondName["Use First Name Column<br/>or Second Column"]
UseSecondName --> ProcessRows["Process Each Row"]
ProcessRows --> CleanPhone["Clean Phone Numbers"]
CleanPhone --> ValidatePhone{"Valid Phone?"}
ValidatePhone --> |Yes| ExtractName["Extract Name"]
ValidatePhone --> |No| SkipRow["Skip Row"]
ExtractName --> AddContact["Add to Contacts List"]
SkipRow --> NextRow["Next Row"]
AddContact --> NextRow
NextRow --> MoreRows{"More Rows?"}
MoreRows --> |Yes| ProcessRows
MoreRows --> |No| ReturnContacts["Return Contacts"]

flowchart TD
PandasTry["Try pandas.read_csv()"] --> PandasSuccess{"Pandas Success?"}
PandasSuccess --> |Yes| PandasProcess["Process with pandas"]
PandasSuccess --> |No| ManualTry["Try manual CSV parsing"]
ManualTry --> ManualSuccess{"Manual Success?"}
ManualSuccess --> |Yes| ManualProcess["Process with csv module"]
ManualSuccess --> |No| ErrorReturn["Return Empty List"]
PandasProcess --> ReturnContacts["Return Contacts"]
ManualProcess --> ReturnContacts
ErrorReturn --> ReturnContacts

flowchart TD
Start([TXT Processing Start]) --> ReadLines["Read All Lines"]
ReadLines --> ProcessLine["Process Each Line"]
ProcessLine --> StripWhitespace["Strip Whitespace"]
StripWhitespace --> CheckEmpty{"Empty Line?"}
CheckEmpty --> |Yes| NextLine["Next Line"]
CheckEmpty --> |No| SplitParts["Split by Separators<br/>(,;\\t|)"]
SplitParts --> FindPhone["Find Phone Number Candidate"]
FindPhone --> CheckPart{"Part Contains<br/>7+ Digits?"}
CheckPart --> |Yes| SetPhone["Set as Phone Candidate"]
CheckPart --> |No| CheckName["Check as Name Candidate"]
CheckName --> SetName["Set as Name Candidate"]
SetPhone --> NextPart["Next Part"]
SetName --> NextPart
NextPart --> MoreParts{"More Parts?"}
MoreParts --> |Yes| FindPhone
MoreParts --> |No| CheckCandidates{"Phone Found?"}
CheckCandidates --> |Yes| ValidatePhone["Validate Phone Number"]
CheckCandidates --> |No| RegexSearch["Regex Phone Search"]
RegexSearch --> RegexFound{"Regex Match?"}
RegexFound --> |Yes| ValidatePhone
RegexFound --> |No| NextLine
ValidatePhone --> PhoneValid{"Valid?"}
PhoneValid --> |Yes| AddContact["Add Contact"]
PhoneValid --> |No| NextLine
AddContact --> NextLine
NextLine --> MoreLines{"More Lines?"}
MoreLines --> |Yes| ProcessLine
MoreLines --> |No| ReturnContacts["Return Contacts"]

classDiagram
class ExcelExtractor {
+detect_phone_columns(df) str[]
+detect_name_columns(df) str[]
+process_xlsx_file(path) Contact[]
+process_xls_file(path) Contact[]
}
class ColumnDetector {
+keywords_phone : str[]
+keywords_name : str[]
+find_matching_columns(df, keywords) str[]
}
class Contact {
+number : string
+name : string?
}
ExcelExtractor --> ColumnDetector : "uses"
ExcelExtractor --> Contact : "creates"
ColumnDetector --> Contact : "maps to"

flowchart TD
Start([Phone Number Input]) --> CheckNull["Check Null/NaN"]
CheckNull --> NullCheck{"Is Null?"}
NullCheck --> |Yes| ReturnNull["Return None"]
NullCheck --> |No| StripWhitespace["Strip Whitespace"]
StripWhitespace --> RemoveSeparators["Remove Separators<br/>(-\\s\\(\\)\\.)"]
RemoveSeparators --> RemoveNonDigits["Remove Non-Digits Except +"]
RemoveNonDigits --> CheckPlus["Check Leading Plus"]
CheckPlus --> RemoveLeadingZeros["Remove Leading Zero<br/>if not international"]
RemoveLeadingZeros --> CheckLength["Check Length > 10"]
CheckLength --> AddPlus["Add + if missing<br/>and international"]
AddPlus --> ExtractDigits["Extract Only Digits"]
ExtractDigits --> ValidateRange{"Length 7-15?"}
ValidateRange --> |No| ReturnNull
ValidateRange --> |Yes| ReturnCleaned["Return Cleaned Number"]

flowchart TD
Start([Manual Numbers Input]) --> SplitByNewlines["Split by Newlines"]
SplitByNewlines --> ProcessNumbers["Process Each Number"]
ProcessNumbers --> SplitBySeparators["Split by Commas/Semicolons"]
SplitBySeparators --> CheckFormat{"Contains<br/>Name: Number?"}
CheckFormat --> |Yes| ExtractPair["Extract Name and Number"]
CheckFormat --> |No| SingleNumber["Single Number Input"]
ExtractPair --> ValidateNumber["Validate Number"]
SingleNumber --> ValidateNumber
ValidateNumber --> CheckValid{"Valid Number?"}
CheckValid --> |Yes| AddContact["Add to Contacts"]
CheckValid --> |No| SkipNumber["Skip Number"]
AddContact --> NextNumber["Next Number"]
SkipNumber --> NextNumber
NextNumber --> MoreNumbers{"More Numbers?"}
MoreNumbers --> |Yes| ProcessNumbers
MoreNumbers --> |No| ReturnResults["Return Results"]

graph TB
subgraph "External Dependencies"
PANDAS[pandas]
OPENPYXL[openpyxl]
XLDRD[xlrd]
RE[re]
CSV[csv]
JSON[json]
OS[os]
SYS[sys]
end
subgraph "Internal Modules"
EXTRACT[extract_contacts.py]
APP[app.py]
MANUAL[parse_manual_numbers.py]
VALIDATE[validate_number.py]
end
EXTRACT --> PANDAS
EXTRACT --> RE
EXTRACT --> CSV
EXTRACT --> JSON
EXTRACT --> OS
EXTRACT --> SYS
APP --> PANDAS
APP --> RE
APP --> CSV
APP --> JSON
APP --> OS
APP --> SYS
MANUAL --> RE
MANUAL --> JSON
MANUAL --> SYS
VALIDATE --> RE
VALIDATE --> JSON
VALIDATE --> SYS
PANDAS --> OPENPYXL
PANDAS --> XLDRD

flowchart TD
Input[File Input] --> ValidateInput["Validate Input"]
ValidateInput --> CheckFile{"File Exists?"}
CheckFile --> |No| ReturnError["Return File Not Found"]
CheckFile --> |Yes| CheckType{"Supported Type?"}
CheckType --> |No| ReturnError
CheckType --> |Yes| ProcessFile["Process File"]
ProcessFile --> TryPandas["Try Pandas Parsing"]
TryPandas --> PandasSuccess{"Pandas Success?"}
PandasSuccess --> |Yes| ReturnSuccess["Return Success"]
PandasSuccess --> |No| TryManual["Try Manual Parsing"]
TryManual --> ManualSuccess{"Manual Success?"}
ManualSuccess --> |Yes| ReturnSuccess
ManualSuccess --> |No| ReturnError
ReturnError --> Cleanup["Cleanup Resources"]
ReturnSuccess --> Cleanup
Cleanup --> End[End Process]