Technical Architecture

# Example: etl/src/bracc_etl/pipelines/cnpj.py
from bracc_etl.base import Pipeline
from bracc_etl.loader import Neo4jBatchLoader
from bracc_etl.transforms import (
    format_cnpj,
    format_cpf,
    normalize_name,
    parse_date,
    deduplicate_rows
)

class CNPJPipeline(Pipeline):
    def extract(self) -> pd.DataFrame:
        """Download and read CNPJ data from Receita Federal"""
        # Download logic
        
    def transform(self, df: pd.DataFrame) -> pd.DataFrame:
        """Normalize and clean data"""
        df['cnpj'] = df['cnpj'].apply(format_cnpj)
        df['name'] = df['razao_social'].apply(normalize_name)
        df['start_date'] = df['data_inicio'].apply(parse_date)
        return deduplicate_rows(df)
        
    def load(self, df: pd.DataFrame, driver: Driver) -> None:
        """Write to Neo4j in batches"""
        loader = Neo4jBatchLoader(driver)
        loader.load_companies(df)

# Run single pipeline
python -m bracc_etl.runner --source cnpj

# Run multiple pipelines
python -m bracc_etl.runner --source cnpj,tse,transparencia

# Full orchestration (all 45+ sources)
make bootstrap-all

// Ownership and control
(Person)-[:PARTNER_OF]->(Company)
(Company)-[:OWNS]->(Company)  // Holdings
(Company)-[:HOLDING_GROUP]->(Holding)

// Transactions
(Company)-[:HAS_CONTRACT]->(Contract)
(Company)-[:SUBMITTED_BID]->(Bid)
(Company)-[:RECEIVED_FINANCE]->(Finance)

// Issues
(Company)-[:HAS_SANCTION]->(Sanction)
(Company)-[:HAS_EMBARGO]->(Embargo)
(Company)-[:UNDER_INVESTIGATION]->(Inquiry)

// Source attribution
(Node)-[:SOURCED_FROM]->(SourceDocument)

api/src/bracc/
├── main.py              # FastAPI app, middleware, lifespan
├── config.py            # Settings (Pydantic BaseSettings)
├── dependencies.py      # Neo4j driver, auth dependencies
├── routers/             # API endpoints
│   ├── public.py        # Public graph/pattern endpoints
│   ├── meta.py          # Health, stats, sources
│   ├── search.py        # Entity search
│   ├── graph.py         # Graph expansion
│   ├── entity.py        # Entity details
│   ├── patterns.py      # Pattern detection
│   ├── investigation.py # Investigation management
│   └── auth.py          # Authentication
├── services/            # Business logic
│   ├── neo4j_service.py            # Query execution
│   ├── public_guard.py             # Privacy enforcement
│   ├── intelligence_provider.py    # Pattern engine
│   └── source_registry.py          # Data source metadata
├── models/              # Pydantic models
│   ├── entity.py
│   ├── graph.py
│   ├── pattern.py
│   └── investigation.py
├── middleware/          # HTTP middleware
│   ├── security_headers.py
│   ├── cpf_masking.py
│   └── rate_limit.py
└── queries/             # Cypher query templates
    └── *.cypher

# Middleware stack (executed in reverse order)
app.add_middleware(CPFMaskingMiddleware)        # Mask CPF in responses
app.add_middleware(SecurityHeadersMiddleware)   # CSP, HSTS, etc.
app.add_middleware(SlowAPIMiddleware)           # Rate limiting
app.add_middleware(CORSMiddleware)              # CORS headers

# Public-safe defaults enforced in services/public_guard.py
def enforce_person_access_policy(labels: list[str]) -> None:
    """Block Person nodes in public mode"""
    if settings.public_mode and has_person_labels(labels):
        raise HTTPException(403, "Person data not accessible in public mode")

def sanitize_public_properties(props: dict) -> dict:
    """Remove CPF and other sensitive fields"""
    return {k: v for k, v in props.items() if k not in SENSITIVE_KEYS}

PUBLIC_MODE=true                    # Enable public-safe mode
PUBLIC_ALLOW_PERSON=false           # Block Person node access
PUBLIC_ALLOW_ENTITY_LOOKUP=false    # Block direct entity lookup
PUBLIC_ALLOW_INVESTIGATIONS=false   # Block investigation features
PATTERNS_ENABLED=false              # Disable pattern engine

{
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "react-router": "^7.0.0",
    "react-force-graph-2d": "^1.26.0",  // Graph visualization
    "react-hook-form": "^7.71.2",        // Form management
    "zustand": "^5.0.0",                  // State management
    "i18next": "^24.0.0",                 // Internationalization
    "lucide-react": "^0.575.0",          // Icons
    "zod": "^4.3.6"                       // Schema validation
  },
  "devDependencies": {
    "vite": "^6.0.0",
    "typescript": "^5.7.0",
    "vitest": "^3.0.0",
    "@testing-library/react": "^16.0.0"
  }
}

services:
  neo4j:
    image: neo4j:5-community
    ports:
      - "7474:7474"  # Browser
      - "7687:7687"  # Bolt
    environment:
      NEO4J_AUTH: neo4j/${NEO4J_PASSWORD}
      NEO4J_PLUGINS: '["apoc"]'
    volumes:
      - neo4j-data:/data
      - ./infra/neo4j/init.cypher:/var/lib/neo4j/init.cypher
    healthcheck:
      test: cypher-shell -u neo4j -p $NEO4J_PASSWORD "RETURN 1"
      interval: 10s
      retries: 8

  api:
    build: ./api
    ports:
      - "8000:8000"
    environment:
      NEO4J_URI: bolt://neo4j:7687
      NEO4J_PASSWORD: ${NEO4J_PASSWORD}
    depends_on:
      neo4j:
        condition: service_healthy

  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    environment:
      VITE_API_URL: http://localhost:8000
    depends_on:
      api:
        condition: service_healthy

  etl:
    build: ./etl
    profiles: ["etl"]  # Only starts with --profile etl
    volumes:
      - .:/workspace
    depends_on:
      neo4j:
        condition: service_healthy