# extrimian/vcsl architecture

> Architecture diagram of the GitHub repository extrimian/vcsl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/extrimian/vcsl
- Repository: https://github.com/extrimian/vcsl

## Overview

##### Project type and purpose
- This is a microservice-based backend system for managing and verifying the status of verifiable credentials (VCSL).
- It comprises two HTTP API services (VCSL API and IPFS API), a relational database (PostgreSQL), an in-memory lock store (Redis), and integration with IPFS and a blockchain/Web3 layer.

##### File structure
- Top level:
- docker-compose.yml – orchestrates containers for all services and data stores.
- ipfs_api/ – standalone microservice for uploading and resolving on IPFS/IPNS.
- vcsl_api/ – main microservice exposing business endpoints.
- pg_hba.conf – database auth config.
- ipfs_api: a minimal FastAPI or Flask-style app (main.py, dto.py), Dockerfile and startup script.
- vcsl_api: layered structure:
- main.py – entry point and router registration.
- routers/ – HTTP route handlers for bit arrays, web3, health.
- services/ – business logic and integrations: IPFS, Redis locks, caching, Web3, bit array operations.
- persistance/ – Postgres DAO and datastore implementation.
- models/ – data transfer objects and domain types.
- misc/ – dependency injection and scheduling.
- resources/ – smart contract ABI.
- test/ – Postman collection and pytest fixtures.

##### README for additional insights
- The system uses a bit array where each bit represents credential status.
- Persistence methods: IPFS, SQL DB, blockchain.
- Redis is used strictly for distributed locks.
- Exposed endpoints cover health, bit-array CRUD and operations, plus Web3 issuer and VCSL registration.

##### Detail and essential elements
- Docker Compose network to show that services share an internal bridge network.
- Critical interactions such as locks and caching.
- Scheduled/background tasks invoking Web3 or IPFS.
- If space permits, illustrate the layer breakdown inside the VCSL API boundary: routers → services → persistence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Compose Network" 
        direction TB
        DC["docker-compose.yml"]:::orchestration
        subgraph "IPFS API Service" 
            direction TB
            IPFSMain["main.py"]:::service
            IPFSDTO["dto.py"]:::service
            IPFSDocker["Dockerfile"]:::service
            IPFSStart["start_ipfs.sh"]:::service
            IPFSReq["requirements.txt"]:::service
        end
        subgraph "VCSL API Service" 
            direction TB
            VMain["main.py"]:::service
            subgraph "Routers"
                direction TB
                BR["rout_bitarray.py"]:::controller
                WR["rout_web3.py"]:::controller
                HR["rout_health.py"]:::controller
            end
            subgraph "Services"
                direction TB
                SB["serv_bitarray.py"]:::service
                SI["serv_ipfs.py"]:::service
                SW3["serv_web3.py"]:::service
                SLk["serv_lock.py"]:::service
                SRd["serv_redis.py"]:::service
                SC["serv_cache.py"]:::service
                SH["serv_health.py"]:::service
                SK["serv_key.py"]:::service
            end
            subgraph "Persistence"
                direction TB
                DAOB["dao_bitarray.py"]:::persistence
                DSB["datastore_postgres.py"]:::persistence
            end
            subgraph "Models"
                direction TB
                MB["bitarray.py"]:::model
                MI["ipfs_dto.py"]:::model
            end
            DI["di_init.py"]:::misc
            SCH["scheduler.py"]:::misc
            ABI["vcsl_abi.json"]:::resources
            VReq["requirements.txt"]:::service
            subgraph "Tests"
                direction TB
                TestDir["vcsl_api/test/"]:::test
                TestColl["VCSL API Collection.postman_collection.json"]:::test
                Conftest["conftest.py"]:::test
                TestAll["test_all.py"]:::test
            end
        end
        Pg["pg_hba.conf"]:::config
    end

    Client["Issuer / Verifier Client"]:::client
    Postgres["PostgreSQL"]:::db
    Redis["Redis"]:::db
    IPFSNet["IPFS Network"]:::external
    BCNet["Blockchain Network"]:::external

    Client -->|REST| VMain
    Client -->|REST| IPFSMain
    VMain -->|loads routers| BR
    VMain -->|loads routers| WR
    VMain -->|loads routers| HR
    BR -->|calls| SB
    WR -->|calls| SW3
    HR -->|calls| SH
    SB -->|uses| DAOB
    SB -->|uses| DSB
    SI -->|HTTP REST| IPFSMain
    SI -->|HTTP REST| IPFSDTO
    SLk -->|TCP| Redis
    SRd -->|TCP| Redis
    SC -->|caching| DSB
    SW3 -->|RPC Web3| BCNet
    SCH -->|schedules| SI
    SCH -->|schedules| SW3
    BR -->|DTOs| MB
    SI -->|DTOs| MI
    DAOB -->|SQL| Postgres
    DSB -->|SQL| Postgres
    IPFSMain -->|IPFS API| IPFSNet
    VMain -->|Web3| BCNet

    subgraph DataStores
        direction TB
        Postgres
        Redis
    end

    subgraph ExternalNetworks
        direction TB
        IPFSNet
        BCNet
    end

    classDef service fill:#D0E8FF,stroke:#0057D9
    classDef controller fill:#E8F4FF,stroke:#0057D9
    classDef db fill:#DFF2D8,stroke:#2E7D32
    classDef external fill:#FFE6CC,stroke:#E65100
    classDef client fill:#F0F0F0,stroke:#616161
    classDef orchestration fill:#E0F7FA,stroke:#00838F
    classDef persistence fill:#E8F4FF,stroke:#2E7D32
    classDef model fill:#FFF3E0,stroke:#EF6C00
    classDef misc fill:#F3E5F5,stroke:#6A1B9A
    classDef resources fill:#FFFDE7,stroke:#F9A825
    classDef config fill:#ECEFF1,stroke:#546E7A
    classDef test fill:#F9FBE7,stroke:#827717

    click DC "https://github.com/extrimian/vcsl/blob/conflict-merger/docker-compose.yml"
    click IPFSMain "https://github.com/extrimian/vcsl/blob/conflict-merger/ipfs_api/main.py"
    click IPFSDTO "https://github.com/extrimian/vcsl/blob/conflict-merger/ipfs_api/dto.py"
    click IPFSDocker "https://github.com/extrimian/vcsl/tree/conflict-merger/ipfs_api/Dockerfile"
    click IPFSStart "https://github.com/extrimian/vcsl/blob/conflict-merger/ipfs_api/start_ipfs.sh"
    click IPFSReq "https://github.com/extrimian/vcsl/blob/conflict-merger/ipfs_api/requirements.txt"
    click VMain "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/main.py"
    click BR "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/routers/rout_bitarray.py"
    click WR "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/routers/rout_web3.py"
    click HR "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/routers/rout_health.py"
    click SB "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/services/serv_bitarray.py"
    click SI "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/services/serv_ipfs.py"
    click SW3 "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/services/serv_web3.py"
    click SLk "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/services/serv_lock.py"
    click SRd "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/services/serv_redis.py"
    click SC "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/services/serv_cache.py"
    click SH "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/services/serv_health.py"
    click SK "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/services/serv_key.py"
    click DAOB "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/persistance/dao_bitarray.py"
    click DSB "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/persistance/datastore_postgres.py"
    click MB "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/models/bitarray.py"
    click MI "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/models/ipfs_dto.py"
    click DI "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/misc/di_init.py"
    click SCH "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/misc/scheduler.py"
    click ABI "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/resources/smart_contracts/vcsl_abi.json"
    click Pg "https://github.com/extrimian/vcsl/blob/conflict-merger/pg_hba.conf"
    click TestDir "https://github.com/extrimian/vcsl/tree/conflict-merger/vcsl_api/test/"
    click TestColl "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/test/VCSL API Collection.postman_collection.json"
    click Conftest "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/test/conftest.py"
    click TestAll "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/test/test_all.py"
    click VReq "https://github.com/extrimian/vcsl/blob/conflict-merger/vcsl_api/requirements.txt"
    click IReq "https://github.com/extrimian/vcsl/blob/conflict-merger/ipfs_api/requirements.txt"
```
