Solution Architecture

The application leverages blockchain (all sensible data about vehicles and participants) and IPFS (metadata + images).

Ethereum blockchain allow distributed and controlled environment to store important information without worrying that data could be amended/faked. Critical data about vehicle is stored on-chain:

vin - vehicle identification number (assigned by manufacturer)
make - manufacturer name
model - vehicle model (assigned by manufacturer)
color - color (assigned by manufacturer)
year - year of vehicle issue (assigned by manufacturer)
maxMileage - max mileage (assigned by manufacturer)
engineSize - engine size in cubic centimeters (assigned by manufacturer)
tokenUri - IPFS link to metadata json with ERC721Metadata schema (assigned by manufacturer)

Due to expense of the blockchain storage it was decided to move everything else off-chain and store in immutable way on IPFS to avoid data loss and eliminate possibility of forgery. So smart contract is enforcing that all references to external storage should be IPFS links.

Main components

Application files are loaded from IPFS
Metamask is used to authenticate and authorize user. Wallet address is used to fetch user roles from blockchain using getRoles(addr) method
Communication with blockchain is implemented via HTTP gateway. It could be any gateway that supports blockchain RPC
User can upload images for managed entities (Manufacturers/Service Factories/Police Departments), for vehicle (vehicle image), and associated metadata for everything (managed entities, vehicle, police and service log entries)

All 3rd party services could be replaced with local instances of blockchain full/light client (for blockchain interaction) and ipfs local app (for media/metadata upload and pinning), so there will be no dependencies on 3rd party services and application would have no single point of failure. For this project it is the simplest option to leverage these services to have application without any backend.

Implementation details

Current implementation of smart contract have 4 distinct roles:

Government
Manufacturer
Service Factory
Police Department

If someone does not have explicit role defined it has implicit readonly role with ability to transfer owned vehicles.

Every role has its own set of methods that are allowed to be executed, please check Smart Contracts.

Smart contract class diagram

Immutable metadata

Every entity in the project have some attributed stored on chain and off-chain metadata stored on IPFS. All managed entities (Manufacturers, Service Factories, and Police Departments) have standard set of attributes from Entity struct:

struct Entity {
    address addr;       // participant address
    string name;        // participant name
    State state;        // participant state
    string metadataUri; // everything else is off-chain in metadata JSON
}

Manufacturers

Example metadata for manufacturer (stored on IPFS). Please note that image attribute is pointing also to IPFS - this is desirable but not enforced.

{
  "name": "Porsche",
  "image": "https://ipfs.io/ipfs/QmPAYiSEeggcPBAwUqrNWvPHYpJKKwVxFGJhUSGKJVFWTA",
  "description": "Dr.-Ing. h.c. F. Porsche AG, usually shortened to Porsche, is a German automobile manufacturer specializing in high-performance sports cars, SUVs and sedans, headquartered in Stuttgart, Baden-Württemberg, Germany",
  "external_uri": "https://www.kia.com/us/en",
  "attributes": [
  ]
}