CCDExplorer is the open-source Concordium blockchain explorer that powers ccdexplorer.io, the public API, and the user-facing Notification Bot. The codebase collects on-chain data straight from a Concordium node, enriches it through background services, and serves it via FastAPI applications for browsers, bots, and programmatic clients.

• Comprehensive Concordium coverage – blocks, transactions, accounts, smart contracts, and modules are indexed in real time, with every-block workers tracking chain health, new accounts, and new or upgraded contracts/modules.
• Developer-friendly API – FastAPI-powered endpoints expose raw chain data alongside derived metrics for integrations, trading dashboards, or research. Public Swagger docs are available at /docs, with schemas derived from the gRPC definitions that the components share.
• Notifications and user tools – the notification bot lets users subscribe to account, contract, or chain events directly from ccdexplorer.io, backed by the same services that drive the explorer frontend.
• On-chain analytics – scheduled jobs compute data sets such as transactions by type, per-project usage, unique address counts, daily holder & limit statistics, and realized price series to give Concordium participants contextual insights.
• Polylith monorepo – the repository uses Polylith for Python to keep components, bases, and projects isolated yet composable, making it easy to reuse bricks across services.

flowchart TD
    
    subgraph EXT[Concordium]
        chain[(Nodes 2x mainet, 2x testnet)]
        %% web((Explorer Users))
        %% botusers((Telegram / Email Users))
    end
    
    subgraph CORE[Core Infrastructure]
        mongo[(MongoDB 3 Member Replica Set)]
        redis[(Redis + Celery Broker)]
        tooter[(Apprise Notifications)]
    end

    subgraph INGEST[Real-time Ingestion]
        heartbeat[Heartbeat]
        analyzer[Block Analyzer]
    end

    subgraph MICRO[Microservices]
        ms_accounts[MS Accounts]
        ms_events[MS Events & Impacted]
        ms_indexers[MS Indexers]
        ms_instances[MS Instances]
        ms_modules[MS Modules]
        ms_metadata[MS Metadata]
        ms_token[MS Token Accounting]
        ms_plt[MS PLT]
        %% ms_bot_sender[MS Bot Sender]
    end

    subgraph ANALYTICS[Analytics]
        accounts[Accounts Retrieval]
        dag_nightrunner[Dagster Nightrunner]
        dag_recurring[Dagster Recurring]
        dag_paydays[Dagster Paydays]
    end
   subgraph Pipelines[Analytics & Events]
      INGEST[Real-time Ingestion]
      MICRO[Microservices]
      ANALYTICS[Analytics]
    end

    subgraph APPS[User-facing]
        api[API]
        site[Site]
        bot[Bot]
    end
    chain --> ANALYTICS --> mongo
    
    chain --> INGEST --> mongo
    analyzer --> redis
    chain --> api
    chain --> MICRO
    

    
    redis --> MICRO --> mongo
    MICRO <--> mongo
    
    mongo --> api --> site
    api --> bot
    redis <--> api
    
    bot  --> tooter 
    
    

Key Polylith bricks live under projects/ (deployable services) and components/ (shared code). Below is the actual layout currently in use:

See the documentation for a deeper dive into each brick and service.

1. Install dependencies

   uv sync

2. Configure environment – copy .env.sample to .env and set a Concordium node endpoint and CCDExplorer API key (keys are domain-scoped, so match the API base you target).
3. Run the explorer site

   uvicorn projects.site.asgi:app --loop asyncio --host 0.0.0.0 --port 8000

4. Run the public API

   uvicorn projects.api.asgi:app --loop asyncio --port 7000

5. Execute tests & formatting

   just test      # pytest with coverage
   just lint      # ruff linting
   just format    # ruff formatting

A Dockerfile is also provided if you prefer containerized builds of the site or API.

The full architecture, component glossary, and deployment details live at docs.ccdexplorer.io. The documentation mirrors the Polylith structure and links to project-specific guides (site, API, bot, timed services, and every-block workers).

Issues and pull requests are welcome. Please open a discussion for larger changes so we can ensure compatibility with the production explorer and downstream services. When contributing:

• keep bricks reusable across projects,
• add tests alongside new functionality,
• run just lint and just test before submitting.

Thanks for helping grow the Concordium ecosystem!