# akshit819/ace_data architecture

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

- Interactive diagram: https://gitdiagram.com/akshit819/ace_data
- Repository: https://github.com/akshit819/ace_data

## Overview

1. **Purpose and execution model**
   - This repository is a **Windows-only batch automation tool** for processing a list of companies from `ace.csv`, refreshing a Microsoft Excel template through the **AccEquity XL NXT** add-in, and then uploading the generated workbooks to **tickercharcha.com**.

2. **Primary entry point**
   - `main.py` is the orchestration layer. It likely coordinates the full loop: load configuration, authenticate to the API, iterate over CSV rows, drive Excel automation, save output files, and upload each file.

3. **Configuration boundary**
   - `config.py` is the central settings loader, reading paths, credentials, retry counts, refresh timing, and cell targets from environment/configuration.
   - This keeps runtime parameters outside the code and allows the same workflow to run against different CSVs, templates, and output folders.

4. **Input data source**
   - `ace.csv` is the operational input feed.
   - Each row contains an **Accord Code** and **Company Name**; the code becomes the Excel input value, while the company name is used to name the final workbook.

5. **Excel automation subsystem**
   - `excel_automation.py` is the main boundary to Microsoft Excel via **COM automation**.
   - Its responsibilities are likely:
     - open a copy of the template workbook,
     - write the Accord Code into the configured cell,
     - trigger `RefreshAll` so the AccEquity add-in fetches data,
     - wait for the refresh to settle,
     - save the finished workbook to the output folder.
   - This subsystem depends on Excel being installed locally and on the AccEquity add-in being available.

6. **Template-driven workbook generation**
   - `Template NBFC-Final.xlsx` is the workbook seed that gets duplicated and populated per company.
   - The architecture is file-based rather than database-based: each company becomes an independent Excel artifact on disk.

7. **API upload subsystem**
   - `api_client.py` encapsulates authentication and file upload to the external tickercharcha.com API.
   - The README indicates it logs in once at startup, extracts a token from common response fields, and re-authenticates automatically if upload requests receive 401/403 responses.

8. **Cross-cutting logging**
   - `logger_setup.py` centralizes log configuration.
   - The system produces both an audit log and an error-only log, plus console output, which is important because the workflow is long-running and continues past per-company failures.

9. **End-to-end data flow**
   - The flow is: **CSV row → Excel template copy → COM write + refresh → saved workbook → API upload → logs**.
   - Each company is processed independently, so failure in one row does not stop the batch.

10. **Error-handling and retry boundaries**
   - The architecture is designed for resilience at two fragile points:
     - Excel automation/refresh can retry when Excel or the add-in is slow or temporarily unavailable.
     - Uploads can retry and re-authenticate when the API token expires.
   - The main loop appears to isolate failures per company rather than failing the whole batch.

11. **Runtime and infrastructure assumptions**
   - The project depends on a **local Windows desktop environment** with **Python 3.10+**, **Microsoft Excel**, and the COM stack provided by `pywin32` or equivalent dependencies.
   - It is not a cloud service or server application; the “infrastructure” is the operator’s workstation plus external API access.

12. **Repository shape**
   - The repo is intentionally small and modular: orchestration in `main.py`, configuration in `config.py`, Excel integration in `excel_automation.py`, API integration in `api_client.py`, and logging in `logger_setup.py`.
   - That separation makes the architecture easy to diagram as three main zones: **input/config**, **Excel generation**, and **API delivery**, with logging spanning all of them.

Main entry points: [`main.py`](https://github.com/akshit819/ace_data/blob/main/main.py) (Main loop), [`excel_automation.py`](https://github.com/akshit819/ace_data/blob/main/excel_automation.py) (Excel automation), [`logger_setup.py`](https://github.com/akshit819/ace_data/blob/main/logger_setup.py) (Logging), [`api_client.py`](https://github.com/akshit819/ace_data/blob/main/api_client.py) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input_config["Input & config"]
  node_config["Settings<br/>config<br/>[config.py]"]
  node_csv["ACE list<br/>input csv<br/>[ace.csv]"]
  node_template["Workbook seed<br/>excel template"]
end

subgraph group_excel_flow["Excel generation"]
  node_excel["Excel automation<br/>com automation"]
  node_open_copy["Open copy<br/>excel step"]
  node_write_code["Write code<br/>excel step"]
  node_refresh["Refresh data<br/>excel step"]
  node_save_workbook["Save workbook<br/>excel step"]
end

subgraph group_delivery["API delivery"]
  node_api["API client<br/>http client<br/>[api_client.py]"]
  node_login["Login<br/>auth step"]
  node_upload["Upload file<br/>api step"]
  node_retry_auth(("Retry auth<br/>resilience"))
end

subgraph group_ops["Operations"]
  node_main["Main loop<br/>orchestrator<br/>[main.py]"]
  node_logger{{"Logging<br/>observability<br/>[logger_setup.py]"}}
  node_runtime[("Windows desktop<br/>runtime")]
end

node_main -->|"load settings"| node_config
node_main -->|"iterate rows"| node_csv
node_main -->|"generate workbook"| node_excel
node_main -->|"upload artifact"| node_api
node_main -->|"write logs"| node_logger
node_excel -->|"seed from"| node_template
node_excel -->|"creates"| node_open_copy
node_open_copy -->|"passes workbook"| node_write_code
node_write_code -->|"triggers"| node_refresh
node_refresh -->|"produces"| node_save_workbook
node_excel -.->|"depends on"| node_runtime
node_api -->|"authenticate"| node_login
node_api -->|"send file"| node_upload
node_upload -.->|"on 401/403"| node_retry_auth
node_retry_auth -->|"renew token"| node_login
node_logger -.->|"observe"| node_main
node_logger -.->|"observe"| node_excel
node_logger -.->|"observe"| node_api

click node_main "https://github.com/akshit819/ace_data/blob/main/main.py"
click node_config "https://github.com/akshit819/ace_data/blob/main/config.py"
click node_csv "https://github.com/akshit819/ace_data/blob/main/ace.csv"
click node_template "https://github.com/akshit819/ace_data/blob/main/Template NBFC-Final.xlsx"
click node_excel "https://github.com/akshit819/ace_data/blob/main/excel_automation.py"
click node_api "https://github.com/akshit819/ace_data/blob/main/api_client.py"
click node_logger "https://github.com/akshit819/ace_data/blob/main/logger_setup.py"

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_config,node_csv,node_template toneBlue
class node_excel,node_open_copy,node_write_code,node_refresh,node_save_workbook toneAmber
class node_api,node_login,node_upload,node_retry_auth toneMint
class node_main,node_logger,node_runtime toneRose
```

## Components

### Input & config

Operational inputs and runtime settings.

- [Settings](https://github.com/akshit819/ace_data/blob/main/config.py): config · Loads paths, credentials, retry values, and cell targets. · `config.py`
- [ACE list](https://github.com/akshit819/ace_data/blob/main/ace.csv): input csv · Per-company source rows with Accord Code and Company Name. · `ace.csv`
- [Workbook seed](https://github.com/akshit819/ace_data/blob/HEAD/Template%20NBFC-Final.xlsx): excel template · Base workbook copied for each company output. · `Template NBFC-Final.xlsx`

### Excel generation

Windows COM automation that produces the workbooks.

- [Excel automation](https://github.com/akshit819/ace_data/blob/main/excel_automation.py): com automation · Windows Excel boundary for opening, writing, refreshing, and saving workbooks. · `excel_automation.py`
- **Open copy**: excel step · Creates a per-company workbook from the template.
- **Write code**: excel step · Places the Accord Code into the configured worksheet cell.
- **Refresh data**: excel step · Triggers Excel refresh so the AccEquity add-in fetches updated values.
- **Save workbook**: excel step · Writes the finished workbook to the output folder.

### API delivery

Upload and session handling for the external service.

- [API client](https://github.com/akshit819/ace_data/blob/main/api_client.py): http client · Handles login, token reuse, re-authentication, and file upload. · `api_client.py`
- **Login**: auth step · Authenticates to the tickercharcha.com API and stores a token.
- **Upload file**: api step · Posts generated workbooks to the external service.
- **Retry auth**: resilience · Re-authenticates when uploads return unauthorized responses.

### Operations

Cross-cutting orchestration and logging.

- [Main loop](https://github.com/akshit819/ace_data/blob/main/main.py): orchestrator · Coordinates the batch workflow across CSV, Excel, and uploads. · `main.py`
- [Logging](https://github.com/akshit819/ace_data/blob/main/logger_setup.py): observability · Central log configuration for audit, error, and console output. · `logger_setup.py`
- **Windows desktop**: runtime · Local Python and Microsoft Excel execution environment with COM support.

## Connections

- Main loop → Settings: load settings · Reads runtime parameters and file locations.
- Main loop → ACE list: iterate rows · Processes each company independently from the input list.
- Main loop → Excel automation: generate workbook · Delegates per-company workbook creation and refresh.
- Main loop → API client: upload artifact · Sends each completed workbook to the external API.
- Main loop → Logging: write logs · Emits progress, audit, and error messages.
- Excel automation → Workbook seed: seed from · Uses the template workbook as the starting artifact.
- Excel automation → Open copy: creates · Opens a company-specific copy of the template.
- Open copy → Write code: passes workbook · Hands the workbook to the cell-writing step.
- Write code → Refresh data: triggers · Starts refresh after the input value is written.
- Refresh data → Save workbook: produces · Saves the refreshed workbook to disk.
- Excel automation → Windows desktop: depends on · Requires local Windows Excel and COM automation.
- API client → Login: authenticate · Obtains an initial access token.
- API client → Upload file: send file · Uploads generated workbook files.
- Upload file → Retry auth: on 401/403 · Re-authenticates when the token expires or is rejected.
- Retry auth → Login: renew token · Fetches a fresh token before retrying upload.
- Logging → Main loop: observe · Captures long-running batch progress and failures.
- Logging → Excel automation: observe · Records Excel automation warnings and errors.
- Logging → API client: observe · Records API authentication and upload events.