# ayerdines/meroshare-scripts architecture

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

- Interactive diagram: https://gitdiagram.com/ayerdines/meroshare-scripts
- Repository: https://github.com/ayerdines/meroshare-scripts

## Overview

#### Purpose and Execution Model
This is a Python CLI for bulk MeroShare IPO workflows: list open ordinary-share issues, inspect per-account application status, submit IPO applications, and generate allotment reports. The sole executable entry point is `main.py`; shared constants are in `constants.py`.

#### CLI Orchestration
`main.py` parses shell flags and selects one of three primary modes:
- Default: discover open IPOs and show whether configured users have applied.
- `--apply`: submit a selected company share ID and quantity.
- `--report`: generate allotment-status reports.
The optional `--user` flag constrains all modes to one account rather than the full account set.

Paths: `main.py`, `constants.py`

#### Account Input Boundary
Credentials/account metadata are loaded from a local CSV file, expected to be created as `accounts.csv` using the documented schema in `accounts.csv.example`. This is the operational boundary for bulk actions: each selected account is processed independently, enabling all-account execution and user filtering.

Paths: `accounts.csv.example`, `main.py`

#### IPO Discovery and Status Checking
The default flow queries MeroShare issue data, filters to currently open ordinary IPO shares, then checks application state for each selected account. It exposes the company share ID needed by the apply flow and distinguishes applied versus unapplied status.

Paths: `main.py`, `constants.py`

#### Bulk Application Stage
Application mode requires `--company-share-id`; `--number-of-shares` defaults to 10. The workflow iterates selected accounts, checks whether each account has already applied for the requested issue, skips duplicates, and submits only missing applications. This pre-check is the key idempotency guard for repeated bulk runs.

Paths: `main.py`

#### Allotment Reporting Stage
Report mode retrieves IPO allotment outcomes for one account or all configured accounts. It is separate from application submission and is controlled by `--report`, allowing post-issue result collection without changing application state.

Paths: `main.py`

#### Runtime and External Dependencies
The repository targets Python 3 and is intended for direct local execution (`python3 main.py`). It integrates with MeroShare’s remote service for issue discovery, application-status checks, application submission, and allotment lookup. Local account credentials are sensitive operational input and should remain outside version control; `.gitignore` supports that boundary.

Paths: `main.py`, `.gitignore`, `.tool-versions`

Main entry points: [`main.py`](https://github.com/ayerdines/meroshare-scripts/blob/main/main.py) (CLI entry point), [`constants.py`](https://github.com/ayerdines/meroshare-scripts/blob/main/constants.py) (Shared constants), [`accounts.csv.example`](https://github.com/ayerdines/meroshare-scripts/blob/main/accounts.csv.example) (Account CSV schema), [`.gitignore`](https://github.com/ayerdines/meroshare-scripts/blob/main/.gitignore) (Credential exclusion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI runtime"]
  node_shell(("Shell user<br/>operator"))
  node_main["CLI entry point<br/>Python CLI<br/>[main.py]"]
  node_constants["Shared constants<br/>Python constants<br/>[constants.py]"]
  node_accounts_example["Account CSV schema<br/>CSV example"]
  node_accounts[("Local accounts CSV<br/>sensitive input")]
  node_gitignore["Credential exclusion<br/>Git ignore rules<br/>[.gitignore]"]
  node_output["CLI results<br/>terminal output"]
end

subgraph group_flows["Workflow modes"]
  node_default_flow["Discovery and status mode<br/>default workflow<br/>[main.py]"]
  node_apply_flow["Bulk application mode<br/>--apply workflow<br/>[main.py]"]
  node_idempotency{{"Already-applied guard<br/>pre-submit check<br/>[main.py]"}}
  node_report_flow["Allotment report mode<br/>--report workflow<br/>[main.py]"]
end

subgraph group_external["MeroShare service"]
  node_issue_api[("Issue discovery<br/>remote API")]
  node_application_api[("Application status<br/>remote API")]
  node_submission_api[("IPO submission<br/>remote API")]
  node_allotment_api[("Allotment lookup<br/>remote API")]
end

node_shell -->|"python3 main.py + flags"| node_main
node_constants -->|"shared values"| node_main
node_accounts_example -.->|"documents schema"| node_accounts
node_accounts -->|"selected accounts"| node_main
node_gitignore -.->|"protects local file"| node_accounts
node_main -->|"default"| node_default_flow
node_main -->|"--apply"| node_apply_flow
node_main -->|"--report"| node_report_flow
node_default_flow -->|"query issues"| node_issue_api
node_default_flow -->|"check each account"| node_application_api
node_issue_api -->|"open ordinary shares"| node_default_flow
node_application_api -->|"applied/unapplied"| node_default_flow
node_apply_flow -->|"per account and issue"| node_idempotency
node_idempotency -->|"check existing application"| node_application_api
node_idempotency -->|"submit only if missing"| node_submission_api
node_report_flow -->|"retrieve outcomes"| node_allotment_api
node_default_flow -->|"issues and statuses"| node_output
node_apply_flow -->|"submission results"| node_output
node_report_flow -->|"allotment report"| node_output

click node_main "https://github.com/ayerdines/meroshare-scripts/blob/main/main.py"
click node_constants "https://github.com/ayerdines/meroshare-scripts/blob/main/constants.py"
click node_accounts_example "https://github.com/ayerdines/meroshare-scripts/blob/main/accounts.csv.example"
click node_gitignore "https://github.com/ayerdines/meroshare-scripts/blob/main/.gitignore"
click node_default_flow "https://github.com/ayerdines/meroshare-scripts/blob/main/main.py"
click node_apply_flow "https://github.com/ayerdines/meroshare-scripts/blob/main/main.py"
click node_idempotency "https://github.com/ayerdines/meroshare-scripts/blob/main/main.py"
click node_report_flow "https://github.com/ayerdines/meroshare-scripts/blob/main/main.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_shell,node_main,node_constants,node_accounts_example,node_accounts,node_gitignore,node_output toneBlue
class node_default_flow,node_apply_flow,node_idempotency,node_report_flow toneAmber
class node_issue_api,node_application_api,node_submission_api,node_allotment_api toneMint
```

## Components

### CLI runtime

- **Shell user**: operator
- [CLI entry point](https://github.com/ayerdines/meroshare-scripts/blob/main/main.py): Python CLI · Parses flags, selects accounts, and orchestrates workflows. · `main.py`
- [Shared constants](https://github.com/ayerdines/meroshare-scripts/blob/main/constants.py): Python constants · `constants.py`
- [Account CSV schema](https://github.com/ayerdines/meroshare-scripts/blob/main/accounts.csv.example): CSV example · Documents the required local account input format. · `accounts.csv.example`
- **Local accounts CSV**: sensitive input · Credentials and account metadata for bulk processing.
- [Credential exclusion](https://github.com/ayerdines/meroshare-scripts/blob/main/.gitignore): Git ignore rules · Keeps local account input outside version control. · `.gitignore`
- **CLI results**: terminal output · Shows issues, application state, and allotment reports.

### Workflow modes

- [Discovery and status mode](https://github.com/ayerdines/meroshare-scripts/blob/main/main.py): default workflow · Lists open ordinary IPOs and per-account application state. · `main.py`
- [Bulk application mode](https://github.com/ayerdines/meroshare-scripts/blob/main/main.py): --apply workflow · Applies the requested share quantity to eligible accounts. · `main.py`
- [Already-applied guard](https://github.com/ayerdines/meroshare-scripts/blob/main/main.py): pre-submit check · Skips accounts that already applied for the selected issue. · `main.py`
- [Allotment report mode](https://github.com/ayerdines/meroshare-scripts/blob/main/main.py): --report workflow · Retrieves post-issue outcomes without submitting applications. · `main.py`

### MeroShare service

- **Issue discovery**: remote API · Supplies IPO issue data.
- **Application status**: remote API · Returns account application state by issue.
- **IPO submission**: remote API
- **Allotment lookup**: remote API

## Connections

- Shell user → CLI entry point: python3 main.py + flags
- Shared constants → CLI entry point: shared values
- Account CSV schema → Local accounts CSV: documents schema
- Local accounts CSV → CLI entry point: selected accounts
- Credential exclusion → Local accounts CSV: protects local file
- CLI entry point → Discovery and status mode: default
- CLI entry point → Bulk application mode: --apply
- CLI entry point → Allotment report mode: --report
- Discovery and status mode → Issue discovery: query issues
- Discovery and status mode → Application status: check each account
- Issue discovery → Discovery and status mode: open ordinary shares
- Application status → Discovery and status mode: applied/unapplied
- Bulk application mode → Already-applied guard: per account and issue
- Already-applied guard → Application status: check existing application
- Already-applied guard → IPO submission: submit only if missing
- Allotment report mode → Allotment lookup: retrieve outcomes
- Discovery and status mode → CLI results: issues and statuses
- Bulk application mode → CLI results: submission results
- Allotment report mode → CLI results: allotment report