# youcef3939/auditmind architecture

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

- Interactive diagram: https://gitdiagram.com/youcef3939/auditmind
- Repository: https://github.com/youcef3939/auditmind

## Overview

1. **Overall shape**
   AuditMind is a single Python application organized as a document-analysis pipeline plus a Streamlit dashboard. The core flow is: user uploads a financial statement, the app extracts structured content, retrieves relevant IFRS/IAS guidance, applies rule and LLM-based checks, then formats findings into a memo and PDF.

2. **User-facing entrypoint**
   `dashboard/app.py` is the runtime entrypoint exposed to users. It likely orchestrates the end-to-end workflow, displays compliance findings and risk scores, and provides memo/PDF download. The dashboard is the presentation layer; it should not contain the audit logic itself.

3. **Document ingestion boundary**
   `core/ingestion/` handles the source-document layer. Separate parsers exist for `pdf`, `docx`, and `excel`, with `loader.py` acting as the dispatcher. This is the boundary where unstructured external inputs are converted into internal text/table structures for downstream analysis.

4. **Standards knowledge base**
   `core/standards/` manages IFRS/IAS reference content. `parser.py` likely turns standards text into structured paragraphs, `embedder.py` creates embeddings, and `vector_store.py` / `vector_search.py` persist and query them using FAISS. This is the repo’s retrieval layer for finding relevant accounting paragraphs.

5. **Analysis engine**
   `core/analysis/` contains the compliance reasoning stack. `rules_engine.py` implements deterministic checks for standards-specific requirements, `llm_pipeline.py` provides the generative/semantic analysis layer, and `scoring.py` converts findings into a risk or compliance score. The architecture is hybrid: rule-based validation plus LLM-assisted interpretation.

6. **Data flow through the pipeline**
   The runtime path is: uploaded statement → parser/loader → normalized document data → standards retrieval against embedded IFRS/IAS corpus → analysis via rules + LLM → scored findings. The output of analysis appears to be structured enough to support both a dashboard view and a formal memo export.

7. **Output generation**
   `core/output/formatter.py` appears to turn analysis results into a report-friendly structure, while `core/output/pdf_generator.py` renders the final memo as PDF, using `reportlab` per the README. This is the formatting/export boundary separating analysis results from presentation artifacts.

8. **Offline assets and generated artifacts**
   `data/raw/` contains sample source documents, and `data/standards/` contains prepared standards artifacts such as `embedded_standards.json` and individual IAS/IFRS JSON files. `parsed_data.json` and `output_files/` suggest intermediate and final generated artifacts are stored on disk rather than in a database.

9. **External libraries that materially shape the design**
   The architecture depends on `pdfplumber`, `python-docx`, and `openpyxl` for ingestion; `sentence-transformers` and `faiss-cpu` for semantic retrieval; `transformers` and `torch` for LLM inference; and `reportlab` for PDF creation. These libraries imply a local, file-based, compute-heavy workflow rather than a thin API service.

10. **Key architectural boundaries**
   There are three important separations: document extraction vs. analysis, standards indexing vs. standards querying, and analysis logic vs. presentation/export. That separation makes the system diagram naturally split into input adapters, retrieval knowledge base, reasoning engine, and output/reporting modules.

11. **What to show in an architecture diagram**
   A clear diagram should show the dashboard as the entrypoint, the ingestion modules as the first processing stage, the standards embedding/vector store as a parallel knowledge subsystem, and the analysis engine consuming both extracted document data and retrieved standards. Final arrows should lead from analysis to formatter/PDF generation and then to downloadable outputs.

Main entry points: [`parsed_data.json`](https://github.com/youcef3939/auditmind/blob/main/parsed_data.json) (Parsed data), [`core/ingestion/loader.py`](https://github.com/youcef3939/auditmind/blob/main/core/ingestion/loader.py) (Loader), [`core/standards/vector_search.py`](https://github.com/youcef3939/auditmind/blob/main/core/standards/vector_search.py) (Vector search), [`core/analysis/rules_engine.py`](https://github.com/youcef3939/auditmind/blob/main/core/analysis/rules_engine.py) (Rules engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_dashboard["Dashboard"]
  node_node_dashboard_app["AuditMind UI<br/>streamlit entrypoint<br/>[app.py]"]
end

subgraph group_group_ingestion["Ingestion"]
  node_node_loader["Loader<br/>dispatch layer<br/>[loader.py]"]
  node_node_pdf_parser["PDF parser<br/>document parser<br/>[pdf_parser.py]"]
  node_node_docx_parser["DOCX parser<br/>document parser<br/>[docx_parser.py]"]
  node_node_excel_parser["Excel parser<br/>table parser<br/>[excel_parser.py]"]
end

subgraph group_group_standards["Standards KB"]
  node_node_standards_parser["Standards parser<br/>[parser.py]"]
  node_node_embedder["Embedder<br/>embedding builder<br/>[embedder.py]"]
  node_node_vector_store[("Vector store<br/>faiss index<br/>[vector_store.py]")]
  node_node_vector_search["Vector search<br/>retrieval layer<br/>[vector_search.py]"]
end

subgraph group_group_analysis["Analysis"]
  node_node_rules_engine["Rules engine<br/>deterministic checks<br/>[rules_engine.py]"]
  node_node_llm_pipeline["LLM pipeline<br/>semantic analysis<br/>[llm_pipeline.py]"]
  node_node_scoring(("Scoring<br/>[scoring.py]"))
end

subgraph group_group_output["Output"]
  node_node_formatter["Formatter<br/>[formatter.py]"]
  node_node_pdf_generator["PDF generator<br/>report renderer<br/>[pdf_generator.py]"]
end

subgraph group_group_data["Data"]
  node_node_raw_data["Sample docs<br/>input corpus"]
  node_node_standards_data[("Standards data<br/>knowledge corpus")]
  node_node_parsed_data["Parsed data<br/>intermediate artifact<br/>[parsed_data.json]"]
  node_node_output_files[("Exports<br/>generated artifacts")]
end

node_node_dashboard_app -->|"uploads"| node_node_loader
node_node_dashboard_app -->|"views report"| node_node_formatter
node_node_loader -->|"routes PDF"| node_node_pdf_parser
node_node_loader -->|"routes DOCX"| node_node_docx_parser
node_node_loader -->|"routes Excel"| node_node_excel_parser
node_node_pdf_parser -->|"writes extracted data"| node_node_parsed_data
node_node_docx_parser -->|"writes extracted data"| node_node_parsed_data
node_node_excel_parser -->|"writes extracted data"| node_node_parsed_data
node_node_standards_data -->|"loads standards"| node_node_standards_parser
node_node_standards_parser -->|"chunks to vectors"| node_node_embedder
node_node_embedder -->|"indexes"| node_node_vector_store
node_node_vector_store -->|"serves retrieval"| node_node_vector_search
node_node_parsed_data -->|"analyzes"| node_node_rules_engine
node_node_parsed_data -->|"analyzes"| node_node_llm_pipeline
node_node_vector_search -->|"supplies guidance"| node_node_rules_engine
node_node_vector_search -->|"supplies context"| node_node_llm_pipeline
node_node_rules_engine -->|"findings"| node_node_scoring
node_node_llm_pipeline -->|"findings"| node_node_scoring
node_node_scoring -->|"summarizes"| node_node_formatter
node_node_formatter -->|"renders"| node_node_pdf_generator
node_node_pdf_generator -->|"exports"| node_node_output_files

click node_node_dashboard_app "https://github.com/youcef3939/auditmind/blob/main/dashboard/app.py"
click node_node_loader "https://github.com/youcef3939/auditmind/blob/main/core/ingestion/loader.py"
click node_node_pdf_parser "https://github.com/youcef3939/auditmind/blob/main/core/ingestion/pdf_parser.py"
click node_node_docx_parser "https://github.com/youcef3939/auditmind/blob/main/core/ingestion/docx_parser.py"
click node_node_excel_parser "https://github.com/youcef3939/auditmind/blob/main/core/ingestion/excel_parser.py"
click node_node_standards_parser "https://github.com/youcef3939/auditmind/blob/main/core/standards/parser.py"
click node_node_embedder "https://github.com/youcef3939/auditmind/blob/main/core/standards/embedder.py"
click node_node_vector_store "https://github.com/youcef3939/auditmind/blob/main/core/standards/vector_store.py"
click node_node_vector_search "https://github.com/youcef3939/auditmind/blob/main/core/standards/vector_search.py"
click node_node_rules_engine "https://github.com/youcef3939/auditmind/blob/main/core/analysis/rules_engine.py"
click node_node_llm_pipeline "https://github.com/youcef3939/auditmind/blob/main/core/analysis/llm_pipeline.py"
click node_node_scoring "https://github.com/youcef3939/auditmind/blob/main/core/analysis/scoring.py"
click node_node_formatter "https://github.com/youcef3939/auditmind/blob/main/core/output/formatter.py"
click node_node_pdf_generator "https://github.com/youcef3939/auditmind/blob/main/core/output/pdf_generator.py"
click node_node_raw_data "https://github.com/youcef3939/auditmind/tree/main/data/raw"
click node_node_standards_data "https://github.com/youcef3939/auditmind/tree/main/data/standards"
click node_node_parsed_data "https://github.com/youcef3939/auditmind/blob/main/parsed_data.json"
click node_node_output_files "https://github.com/youcef3939/auditmind/tree/main/output_files"

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_dashboard_app toneBlue
class node_node_loader,node_node_pdf_parser,node_node_docx_parser,node_node_excel_parser toneAmber
class node_node_standards_parser,node_node_embedder,node_node_vector_store,node_node_vector_search toneMint
class node_node_rules_engine,node_node_llm_pipeline,node_node_scoring toneRose
class node_node_formatter,node_node_pdf_generator toneIndigo
class node_node_raw_data,node_node_standards_data,node_node_parsed_data,node_node_output_files toneTeal
```

## Components

### Dashboard

User-facing Streamlit entrypoint and presentation layer.

- [AuditMind UI](https://github.com/youcef3939/auditmind/blob/main/dashboard/app.py): streamlit entrypoint · Runs the user workflow, displays findings, and exposes downloads. · `dashboard/app.py`

### Ingestion

Document loaders and parsers that normalize source files.

- [Loader](https://github.com/youcef3939/auditmind/blob/main/core/ingestion/loader.py): dispatch layer · Routes uploaded files to the correct parser. · `core/ingestion/loader.py`
- [PDF parser](https://github.com/youcef3939/auditmind/blob/main/core/ingestion/pdf_parser.py): document parser · Extracts text and tables from PDF statements. · `core/ingestion/pdf_parser.py`
- [DOCX parser](https://github.com/youcef3939/auditmind/blob/main/core/ingestion/docx_parser.py): document parser · Reads Word-based source documents into structured content. · `core/ingestion/docx_parser.py`
- [Excel parser](https://github.com/youcef3939/auditmind/blob/main/core/ingestion/excel_parser.py): table parser · Extracts spreadsheet statements and tabular data. · `core/ingestion/excel_parser.py`

### Standards KB

IFRS/IAS parsing, embeddings, and vector retrieval.

- [Standards parser](https://github.com/youcef3939/auditmind/blob/main/core/standards/parser.py): standards parser · Converts IFRS/IAS reference text into structured chunks. · `core/standards/parser.py`
- [Embedder](https://github.com/youcef3939/auditmind/blob/main/core/standards/embedder.py): embedding builder · Creates semantic vectors for standards paragraphs. · `core/standards/embedder.py`
- [Vector store](https://github.com/youcef3939/auditmind/blob/main/core/standards/vector_store.py): faiss index · Persists embedded standards for similarity search. · `core/standards/vector_store.py`
- [Vector search](https://github.com/youcef3939/auditmind/blob/main/core/standards/vector_search.py): retrieval layer · Queries the standards index for relevant guidance. · `core/standards/vector_search.py`

### Analysis

Hybrid rule-based and LLM-based compliance reasoning.

- [Rules engine](https://github.com/youcef3939/auditmind/blob/main/core/analysis/rules_engine.py): deterministic checks · Applies accounting rules and standards-specific validations. · `core/analysis/rules_engine.py`
- [LLM pipeline](https://github.com/youcef3939/auditmind/blob/main/core/analysis/llm_pipeline.py): semantic analysis · Performs generative interpretation and contextual reasoning. · `core/analysis/llm_pipeline.py`
- [Scoring](https://github.com/youcef3939/auditmind/blob/main/core/analysis/scoring.py): risk scoring · Converts findings into compliance or risk scores. · `core/analysis/scoring.py`

### Output

Report formatting and PDF generation.

- [Formatter](https://github.com/youcef3939/auditmind/blob/main/core/output/formatter.py): report formatter · Shapes analysis output into a memo-friendly structure. · `core/output/formatter.py`
- [PDF generator](https://github.com/youcef3939/auditmind/blob/main/core/output/pdf_generator.py): report renderer · Produces the final audit/compliance PDF report. · `core/output/pdf_generator.py`

### Data

Sample inputs and generated artifacts stored on disk.

- [Sample docs](https://github.com/youcef3939/auditmind/tree/main/data/raw): input corpus · Example financial statements used to drive the pipeline. · `data/raw`
- [Standards data](https://github.com/youcef3939/auditmind/tree/main/data/standards): knowledge corpus · Prepared IAS/IFRS JSON artifacts and embedded standards. · `data/standards`
- [Parsed data](https://github.com/youcef3939/auditmind/blob/main/parsed_data.json): intermediate artifact · Serialized normalized extraction output. · `parsed_data.json`
- [Exports](https://github.com/youcef3939/auditmind/tree/main/output_files): generated artifacts · Stored output reports generated by the application. · `output_files`

## Connections

- AuditMind UI → Loader: uploads · The dashboard hands the selected source document to the ingestion layer.
- AuditMind UI → Formatter: views report · The UI presents formatted findings and summary output to the user.
- Loader → PDF parser: routes PDF · Dispatches PDF inputs to the PDF parser.
- Loader → DOCX parser: routes DOCX · Dispatches Word inputs to the DOCX parser.
- Loader → Excel parser: routes Excel · Dispatches spreadsheet inputs to the Excel parser.
- PDF parser → Parsed data: writes extracted data · Normalized extraction output is stored for downstream processing.
- DOCX parser → Parsed data: writes extracted data · Normalized extraction output is stored for downstream processing.
- Excel parser → Parsed data: writes extracted data · Normalized extraction output is stored for downstream processing.
- Standards data → Standards parser: loads standards · Prepared IAS/IFRS content is parsed into structured units.
- Standards parser → Embedder: chunks to vectors · Parsed standards are embedded for semantic retrieval.
- Embedder → Vector store: indexes · Embeddings are stored in the FAISS-backed vector index.
- Vector store → Vector search: serves retrieval · The vector index is queried for relevant accounting guidance.
- Parsed data → Rules engine: analyzes · Extracted document content feeds deterministic compliance checks.
- Parsed data → LLM pipeline: analyzes · Extracted content is also interpreted by the LLM layer.
- Vector search → Rules engine: supplies guidance · Retrieved standards paragraphs inform rule-based validation.
- Vector search → LLM pipeline: supplies context · Retrieved standards context conditions the semantic analysis.
- Rules engine → Scoring: findings · Rule outcomes contribute to the final score.
- LLM pipeline → Scoring: findings · LLM-derived observations contribute to the final score.
- Scoring → Formatter: summarizes · Scores and findings are converted into a report structure.
- Formatter → PDF generator: renders · Formatted report content is rendered as PDF.
- PDF generator → Exports: exports · Generated PDF reports are written to the output directory.
