How youcef3939/auditmind works
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 Parsed data · loader.py Loader · vector_search.py Vector search · rules_engine.py Rules engine
Components 18
Dashboard
User-facing Streamlit entrypoint and presentation layer.
- AuditMind UI · Runs the user workflow, displays findings, and exposes downloads.
dashboard/app.py
Ingestion
Document loaders and parsers that normalize source files.
- Loader · Routes uploaded files to the correct parser.
core/ingestion/loader.py - PDF parser · Extracts text and tables from PDF statements.
core/ingestion/pdf_parser.py - DOCX parser · Reads Word-based source documents into structured content.
core/ingestion/docx_parser.py - Excel parser · Extracts spreadsheet statements and tabular data.
core/ingestion/excel_parser.py
Standards KB
IFRS/IAS parsing, embeddings, and vector retrieval.
- Standards parser · Converts IFRS/IAS reference text into structured chunks.
core/standards/parser.py - Embedder · Creates semantic vectors for standards paragraphs.
core/standards/embedder.py - Vector store · Persists embedded standards for similarity search.
core/standards/vector_store.py - Vector search · Queries the standards index for relevant guidance.
core/standards/vector_search.py
Analysis
Hybrid rule-based and LLM-based compliance reasoning.
- Rules engine · Applies accounting rules and standards-specific validations.
core/analysis/rules_engine.py - LLM pipeline · Performs generative interpretation and contextual reasoning.
core/analysis/llm_pipeline.py - Scoring · Converts findings into compliance or risk scores.
core/analysis/scoring.py
Output
Report formatting and PDF generation.
- Formatter · Shapes analysis output into a memo-friendly structure.
core/output/formatter.py - PDF generator · Produces the final audit/compliance PDF report.
core/output/pdf_generator.py
Data
Sample inputs and generated artifacts stored on disk.
- Sample docs · Example financial statements used to drive the pipeline.
data/raw - Standards data · Prepared IAS/IFRS JSON artifacts and embedded standards.
data/standards - Parsed data · Serialized normalized extraction output.
parsed_data.json - Exports · Stored output reports generated by the application.
output_files
Connections 21
- 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.