br-acc/README.md

BR/ACC Open Graph

Language: English | Português (Brasil)

BR/ACC Open Graph is an open-source graph infrastructure for public data intelligence, built as an initiative from World Open Graph. Primary website: bracc.org

What BR/ACC Represents

• Public-interest graph infrastructure for transparency work.
• Reproducible ingestion and processing for public records.
• Investigative signals with explicit methodological caution.

Data patterns from public records are signals, not legal proof.

What Is In This Repository

• Public API (api/)
• ETL pipelines and downloaders (etl/, scripts/)
• Frontend explorer (frontend/)
• Infrastructure and schema bootstrap (infra/)
• Documentation, legal pack, and release gates (docs/, root policies)

Architecture At A Glance

• Graph DB: Neo4j 5 Community
• Backend: FastAPI (Python 3.12+, async)
• Frontend: Vite + React 19 + TypeScript
• ETL: Python (pandas, httpx)
• Infra: Docker Compose

Quick Start

cp .env.example .env
# set at least NEO4J_PASSWORD

make dev

export NEO4J_PASSWORD=your_password
make seed

• API: http://localhost:8000/health
• Frontend: http://localhost:3000
• Neo4j Browser: http://localhost:7474

Repository Map

• api/: FastAPI app, routers, Cypher query loading
• etl/: pipeline definitions and ETL runtime
• frontend/: React application for graph exploration
• infra/: Neo4j initialization and compose-related infra
• scripts/: operational and validation scripts
• docs/: legal, release, and dataset documentation

Operating Modes / Public-Safe Defaults

Use these defaults for public deployments:

• PRODUCT_TIER=community
• PUBLIC_MODE=true
• PUBLIC_ALLOW_PERSON=false
• PUBLIC_ALLOW_ENTITY_LOOKUP=false
• PUBLIC_ALLOW_INVESTIGATIONS=false
• PATTERNS_ENABLED=false
• VITE_PUBLIC_MODE=true
• VITE_PATTERNS_ENABLED=false

Development

# dependencies
cd api && uv sync --dev
cd ../etl && uv sync --dev
cd ../frontend && npm install

# quality
make check
make neutrality

Releases

Track update history in GitHub Releases:

• Releases page
• Release policy

API Surface

Method	Route	Description
GET	/health	Health check
GET	/api/v1/public/meta	Aggregated metrics and source health
GET	/api/v1/public/graph/company/{cnpj_or_id}	Public company subgraph
GET	/api/v1/public/patterns/company/{cnpj_or_id}	Returns 503 while pattern engine is disabled

Brazil Dataset Matrix (Legal Basis)

BR/ACC maintains a legal-basis registry for Brazilian public datasets used in transparency workflows.

Scope	Coverage	Includes legal basis	File
Brazil public data matrix	93 sources	Yes	docs/pt-BR/datasets/matriz-bases-publicas-brasil.md

This matrix includes dataset, disclosure scope, source URL, format, indicative legal foundation, and approximate record volume where available. The current full matrix is maintained in Portuguese (pt-BR).

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for workflow, quality gates, and review expectations.

Contributors

• BRACC Core Team — maintainers
• OpenAI Codex — AI-assisted engineering contributor

Legal & Ethics

• ETHICS.md
• LGPD.md
• PRIVACY.md
• TERMS.md
• DISCLAIMER.md
• SECURITY.md
• ABUSE_RESPONSE.md
• docs/legal/legal-index.md

License

GNU Affero General Public License v3.0