One-Line Idea#

Transform fragmented telecom reclamation evidence and multi-stage engineering processes into a structured, explainable, reviewable workflow—without allowing automated parsing to replace authoritative engineering, customer-impact, billing, field, safety, permit, or operational approvals.

Why This Project Exists#

Telecom copper-reclamation work is not a single document-processing task. It is a cross-functional decision process involving engineering reports, cable and pair records, circuit evidence, planning information, field observations, design packages, quality-control steps, permits, O-Calc activities, customer-impact checks, and operational approvals.

A large part of this work is still coordinated through PDF reports, spreadsheets, emails, manual lookups, and repeated handoffs. Engineers may need to:

• locate and interpret ACR, CAPR, and CPR reports;
• identify cable, count, terminal, circuit, and pair-level information;
• determine whether a pair appears working, assigned, defective, spare, or unresolved;
• reconcile IN COUNT, OUT COUNT, and QUALIFIED PAIRS relationships;
• consolidate evidence into review workbooks;
• compare With-SOW and Without-SOW operating processes;
• estimate where automation could reduce repetitive work;
• retain enough evidence for engineering review and audit.

This project organizes those activities into two complementary layers:

1. Document intelligence and decision support for extracting and normalizing evidence from ACR/CAPR/CPR reports.
2. Workflow modernization for exposing process data through FastAPI and presenting workflow phases, automation opportunities, and savings scenarios in a React/Vite dashboard.

The goal is not automatic decommission authorization. The goal is to reduce avoidable manual effort, improve consistency, make decision reasons visible, and create a foundation for a governed human-review workflow.

Project at a Glance#

What Makes the Platform Different#

The project treats copper reclamation as both an evidence problem and a workflow problem.

Important: The repository name uses “AI-Powered,” but the inspected document-analysis implementation is currently deterministic and rule-based. It is not yet a trained or independently validated machine-learning model.

Reader Walkthrough#

A reader can understand the platform in eight steps:

1. ACR, CAPR, and CPR PDF reports are collected for a candidate reclamation project.
2. The parser extracts text with PyMuPDF and detects the report family.
3. Metadata, cable/count sections, pair rows, statuses, defects, and available circuit identifiers are parsed.
4. Raw statuses are normalized into working, review-required, defective, spare, or unknown categories.
5. Evidence is aggregated into a conservative recommendation: HOLD, ENGINEERING REVIEW REQUIRED, or PROCEED CANDIDATE.
6. Structured results are exported for engineering review in CSV, JSON, or XLSX form.
7. The FastAPI and React layers represent the broader reclamation workflow, including With-SOW and Without-SOW process variants.
8. Human reviewers verify all authoritative systems, field conditions, customer impact, permits, design dependencies, and approved work procedures before any operational action.

Platform Architecture#

The architecture currently contains two main subsystems.

Document Intelligence Pipeline#

The parser follows a structured sequence:

1. Read PDF text.
2. Detect whether the document resembles an ACR, CAPR, or CPR report.
3. Extract report-level metadata.
4. Parse pair-level records and cable/count sections.
5. Preserve the original raw status.
6. Normalize the status for downstream interpretation.
7. Aggregate working, assigned/review, defective, spare, and unknown evidence.
8. Generate a preliminary recommendation and warnings.
9. Export structured review files.

Extracted Information#

Depending on the source report and available text, the parser is designed to organize fields such as:

• source filename and report family;
• report date;
• work center and employee identifier;
• cable identifier and pair range;
• pair number;
• raw pair status;
• normalized status;
• circuit or service identifiers;
• line and pair state;
• binding post and color;
• terminal and location information;
• defect indicators;
• IN COUNT, OUT COUNT, and QUALIFIED PAIRS relationships;
• file-level warnings and recommendation.

For production traceability, every extracted record should additionally retain source page, evidence text, source-file hash, parser version, extraction timestamp, quality flags, and reviewer disposition.

Read the Data Model and Exports Wiki page

Pair-Status Interpretation#

The current rule set uses conservative status categories.

Raw source values must be retained even after normalization. That allows reviewers to inspect exactly what was present in the source report and prevents the normalized label from hiding parsing ambiguity.

Conservative Decision Logic#

The platform deliberately avoids turning report parsing into automatic authorization.

Workflow Variants#

The backend contains two structured process-flow variants.

FastAPI Service#

The backend exposes workflow and savings-related data through FastAPI.

Example savings request:

1
{
2
  "selected_opportunity_ids": ["opp-1"],
3
  "automation_coverage_pct": 50,
4
  "jobs_per_month": 20,
5
  "work_hours_per_day": 8,
6
  "loaded_hourly_rate": 75
7
}

The current documented snapshot notes that some endpoints depend on backend/app/data/automation_opportunities.json, which was not visible in the inspected backend data directory.

Read the API Reference Wiki page

React/Vite Dashboard#

The frontend is designed as an operational visualization layer for:

• comparing With-SOW and Without-SOW processes;
• viewing phase-level sequence and duration;
• displaying workflow summaries and pain points;
• exploring automation opportunities;
• calculating scenario-based time and cost savings;
• presenting a clearer process narrative to engineering and operations stakeholders.

The application uses React, TypeScript, Vite, Tailwind CSS, Framer Motion, and Lucide React.

The repository documentation identifies two imported frontend components—AutomationBacklog and SavingsCalculator—that were not visible in the inspected component directory. These should be restored or replaced before the frontend is described as a clean end-to-end build.

Read the Dashboard and Frontend Wiki page

Generated Outputs#

The parser can support review-oriented outputs such as:

• pair-level CSV;
• ACR count-section CSV;
• project or file decision-summary JSON;
• uploaded-file summary tables;
• XLSX analysis workbooks;
• warnings and reason-code summaries.

Recommended production fields include:

• source filename and cryptographic hash;
• source page and evidence span;
• report type and report date;
• raw and normalized status;
• cable, count, pair, terminal, and circuit identifiers;
• extraction timestamp and parser version;
• validation or quality flags;
• recommendation reason codes;
• reviewer name, review date, disposition, and approval history.

Exports should preserve raw evidence, prevent spreadsheet-formula injection where relevant, classify or watermark sensitive data, and avoid overwriting approved historical records.

Technology Stack#

Repository Structure#

1
AI-Powered-Telecom-Copper-Reclamation-Workflow-Automation-Platform/
2
├── assets/
3
│   └── diagrams/
4
│       ├── platform_architecture.svg
5
│       ├── parser_decision_flow.svg
6
│       └── workflow_variants.svg
7
├── backend/
8
│   ├── app/
9
│   │   ├── data/
10
│   │   │   └── process_flows.json
11
│   │   ├── main.py
12
│   │   └── models.py
13
│   └── requirements.txt
14
├── data/
15
├── docs/
16
│   └── DASHBOARD_DETAILS.md
17
├── frontend/
18
│   ├── src/
19
│   │   ├── components/
20
│   │   ├── App.tsx
21
│   │   ├── api.ts
22
│   │   └── types.ts
23
│   └── package.json
24
├── outputs/
25
├── src/
26
│   └── parser.py
27
├── tests/
28
├── parsed_acr_output.xlsx
29
├── telecom_analysis.xlsx
30
└── README.md

Read the Repository Structure Wiki page

Local Run#

1
python -m venv .venv

1
.\.venv\Scripts\Activate.ps1
2
pip install pandas pymupdf openpyxl pytest

1
source .venv/bin/activate
2
pip install pandas pymupdf openpyxl pytest

1
cd backend
2
python -m venv .venv

1
.\.venv\Scripts\Activate.ps1
2
pip install -r requirements.txt
3
uvicorn app.main:app --reload --port 8000

1
source .venv/bin/activate
2
pip install -r requirements.txt
3
uvicorn app.main:app --reload --port 8000

1
cd frontend
2
npm install
3
npm run dev

1
VITE_API_BASE_URL=http://localhost:8000

Current Implementation Status#

Known Issues#

The current Wiki documents the following visible gaps:

1. automation_opportunities.json is referenced by the API but was not visible in the backend data directory.
2. AutomationBacklog and SavingsCalculator are imported by App.tsx but were not visible in the frontend component directory.
3. Parser dependencies are not declared in the backend requirements file.
4. Parser outputs are not connected to the API and UI.
5. Tests do not yet validate the complete business behavior.
6. Authentication, authorization, secure storage, and audit workflow are not yet visible.
7. No trained and evaluated AI model is present in the inspected implementation.
8. Sample PDF and XLSX files require privacy and approval review.
9. No license file was visible in the documented snapshot.

These limitations are included to keep the portfolio description technically credible and to distinguish the working prototype from the intended production platform.

Read Known Issues and Roadmap

Roadmap#

Security, Privacy, and Claim Boundary#

Telecom engineering documents may contain operationally sensitive information, customer or circuit identifiers, employee identifiers, addresses, facility information, and network-topology details.

Minimum safeguards for any real deployment include:

• synthetic or formally approved redacted data in public repositories;
• encryption in transit and at rest;
• role-based access control;
• strong authentication and authorization;
• secrets outside source control;
• sensitive-field redaction in logs and screenshots;
• retention and deletion rules;
• auditable reviewer and approval history;
• secure export controls;
• human approval before any operational action.

Testing and Validation Strategy#

The current tests are starter/import checks. A production validation program should add:

• synthetic and approved redacted document fixtures;
• report-layout-specific unit tests;
• golden-file regression tests;
• malformed, scanned, rotated, and partially readable PDF cases;
• status-normalization boundary tests;
• count-relationship validation tests;
• decision-logic tests;
• FastAPI success and error tests;
• frontend component and end-to-end tests;
• parser-to-dashboard contract tests;
• security, authorization, and audit tests;
• operational validation against qualified engineering review.

Key measures should include field-level precision and recall, row-level extraction accuracy, unparsed-row rate, false-clear rate, document coverage, reviewer agreement, cycle time, rework rate, and exception rate.

Read Testing and Validation

Complete Wiki Documentation#

Practical Use Cases#

Key Strengths#

• Combines document extraction with workflow modernization.
• Preserves raw source evidence alongside normalized values.
• Uses conservative decisions instead of unsafe automatic clearance.
• Makes the difference between parsing and authorization explicit.
• Documents With-SOW and Without-SOW operating processes.
• Includes a FastAPI backend and React/Vite dashboard foundation.
• Provides structured export examples.
• Includes architecture diagrams and a 16-page GitHub Wiki.
• States implementation gaps and claim boundaries openly.
• Provides a credible path from prototype to governed enterprise platform.

Key Innovation#

The strongest contribution is not an unsupported claim of fully autonomous AI. It is the combination of evidence extraction, conservative decision logic, workflow modeling, explainable outputs, and explicit human-approval boundaries in one documented telecom-reclamation prototype.

The system recognizes that missing parsed evidence is not proof of absence and that a report-based recommendation cannot replace authoritative system and field validation. This is critical in infrastructure workflows where an incorrect “clear” decision could affect active service, customer operations, safety, compliance, or network integrity.

Project Links#

• GitHub Repository
• GitHub Wiki
• README
• Source Parser
• Backend
• Frontend
• Architecture and Design
• Decision Logic
• API Reference
• Known Issues and Roadmap

Conclusion#

The AI-Powered Telecom Copper Reclamation Workflow Automation Platform demonstrates how document intelligence and process automation can be combined to improve a complex engineering workflow.

The parser converts ACR, CAPR, and CPR report content into structured evidence. Conservative decision logic helps distinguish working, unresolved, defective, spare, and unknown pair conditions. The workflow application models two operating variants and creates a foundation for API-driven dashboards, automation backlogs, and scenario-based savings analysis.

The project is most credible when understood as a decision-support prototype and workflow foundation. Its future value depends on rigorous document testing, parser-to-dashboard integration, governed enterprise APIs, strong data protection, measurable operational validation, and mandatory human approval.

Final Thought#

Extract the evidence. Preserve the source. Explain the decision. Never confuse a candidate recommendation with authorization.

ACR/CAPR/CPR parsing · conservative pair-status logic · FastAPI · React/Vite · With-SOW and Without-SOW workflows · governed human review · complete GitHub Wiki