Comprehensive guide for working on MAP PRO, an enterprise XBRL financial filing processing system with strict architectural principles including no hardcoding, market/taxonomy agnostic design, and filesystem-based data management.
Guide for AI assistants working on MAP PRO (Multi-market XBRL Analysis Platform) - a production-grade XBRL financial filing processing system.
MAP PRO processes XBRL filings from regulatory markets (SEC, FCA, ESMA) to extract financial data. Built on strict architectural principles:
1. **Market Agnostic** - Supports any regulatory market
2. **Taxonomy Agnostic** - Handles any XBRL taxonomy
3. **Database Reflects Reality** - Filesystem is source of truth
4. **No Hardcoding** - All configurations externalized
5. **Modular Architecture** - Six independent modules
6. **Output Separation** - Program files vs data files strictly separated
- `database/` - Metadata coordination layer (PostgreSQL + SQLAlchemy)
- `searcher/` - Filing search across regulatory markets
- `downloader/` - Downloads XBRL filings and taxonomies
- `library/` - Taxonomy library management
- `parser/` - Parse XBRL instance documents to JSON
- `mapper/` - Extract financial statements from parsed filings
- `env` - Master configuration file
- `standards.py` - Complete coding standards and validation
- `downloader/` - Downloaded filings and logs
- `taxonomies/` - Standard taxonomies and cache
- `parser/` - Parsed reports and logs
- `mapper/` - Mapped statements and logs
- `database/` - PostgreSQL data files
1. **Read the coding standards**
- Read `/home/user/map_pro/standards.py` completely
- This contains non-negotiable architectural principles
- Run `python standards_checker.py` to verify compliance
2. **Understand the module structure**
- Review the module's README.md if it exists
- Check current git branch
- Verify folder structure with user before creating new files
3. **Review configuration**
- Master config: `/home/user/map_pro/env`
- Module configs in `{module}/core/config_loader.py`
- Never hardcode - always use config loader
#### 1. NO HARDCODE - Nowhere and on no subject
**FORBIDDEN:**
```python
url = "https://data.sec.gov/submissions/CIK0000320193.json"
path = "/home/user/data/filings"
```
**CORRECT:**
```python
from core.config_loader import ConfigLoader
config = ConfigLoader()
url = config.sec_submissions_url.format(cik=cik)
path = config.entities_dir
```
Rules:
#### 2. MARKET AGNOSTIC - Only in `/market/` directory
**FORBIDDEN (outside market/):**
```python
if "us-gaap" in namespace:
# Market-specific logic
```
**CORRECT:**
```python
from xbrl_parser.market import MarketRegistry
validator = MarketRegistry.get_validator(market_code)
validator.validate(filing)
```
Rules:
#### 3. OUTPUT LOCATION - NEVER write to program files
**FORBIDDEN:**
```python
output_path = "xbrl_parser/output/parsed.json" # In program directory!
```
**CORRECT:**
```python
from core.config_loader import ConfigLoader
config = ConfigLoader()
output_path = config.output_parsed_dir / market / company / form / date / "parsed.json"
```
Rules:
#### 4. PATH REGIME CHECK - Before adding ANY path
Before adding a new path:
1. Read `/home/user/map_pro/env` completely
2. Read `core/data_paths.py` to understand path construction
3. Read `core/config_loader.py` to see how paths are loaded
4. Check if required path already exists
5. If exists: USE IT (stop creating duplicates!)
6. If not exists: Add following existing patterns
#### 5. FILE HEADER PATH - Every Python file
**Required first line:**
```python
"""
XML Parser for XBRL documents.
"""
```
Rules:
#### 6. ASCII ONLY - No emojis anywhere
**FORBIDDEN:**
```python
print("✓ Success")
log.info("⚠️ Warning")
```
**CORRECT:**
```python
print("[OK] Success")
log.info("[WARN] Warning")
```
Use: `[OK]` `[FAIL]` `[WARN]` `->` `*` instead of emojis
#### 7. FOLDER TREE - Always verify first
Before writing ANY new files:
1. Ask user for current folder tree (Claude sees files flat)
2. Create virtual copy of folder structure
3. Verify file locations
4. DO NOT forget `__init__.py` files
1. **Setting up:**
```bash
cd map_pro
cd {module} && pip install -r requirements.txt
# Configure /home/user/map_pro/env
cd database && python -m database.operations.initialize
```
2. **While coding:**
- Run `python standards_checker.py` regularly
- Add `# Path:` header to all new files
- Use type hints on all functions
- Write docstrings (Google or NumPy style)
- No hardcoded values - use config loader
3. **Before committing:**
- Run `python standards_checker.py`
- Run `pytest tests/`
- Run `mypy module_name/`
- Run `flake8 module_name/`
- Format: `black module_name/` and `isort module_name/`
4. **Commit conventions:**
- Concise messages focusing on "why" not "what"
- Follow existing commit style (`git log`)
- Analyze ALL changes before drafting message
```python
MAX_CYCLOMATIC_COMPLEXITY = 10
MAX_FUNCTION_LENGTH = 50 # lines
MAX_CLASS_LENGTH = 300 # lines
MAX_LINE_LENGTH = 100 # characters
MIN_UNIT_TEST_COVERAGE = 80%
MIN_INTEGRATION_TEST_COVERAGE = 70%
TARGET_OVERALL_COVERAGE = 95%
```
**database/** - Metadata coordination layer
**searcher/** - Filing search across regulatory markets
**downloader/** - Downloads XBRL filings and taxonomies
**library/** - Taxonomy library management
**parser/** - Parse XBRL instance documents to JSON
**mapper/** - Extract financial statements from parsed filings
```
{module}/tests/
├── unit/
│ ├── test_foundation/
│ ├── test_instance/
│ └── test_taxonomy/
├── integration/
├── regression/
└── fixtures/
```
**Query filings ready for parsing:**
```python
from database.operations import FilingQueries
filings = FilingQueries.get_ready_for_parsing(market='sec', limit=10)
```
**Download filings:**
```bash
cd downloader
python download.py
```
**Parse filing:**
```bash
cd parser
python parser.py --filing-path /mnt/map_pro/downloader/entities/sec/apple/...
```
**Map statements:**
```bash
cd mapper
python mapper.py --parsed-path /mnt/map_pro/parser/parsed_reports/...
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/map-pro-development-guide/raw