3️⃣Day 3 - Define the technical architecture

Define how your solution will work technically

You've made it to Day 3! Well done. Today, you will focus on creating a Technical Architecture Document.

A solid technical architecture document is crucial; the Stellar Community Fund has technical reviewers who will ensure the document is clear and explains your solution in detail.

High-level overview: C4 Diagrams

C4 diagrams (short for "Context, Containers, Components, and Code"), is a visualization tool used in software system design. It provides a structured way to represent different system abstraction levels, from the high-level context to specific code details.

The C4 diagram is divided into four layers: the context, which shows how the system interacts with its environment; containers, representing the main parts of the system; components, detailing the internal pieces of the containers; and, finally, code, which focuses on detailed implementation.

This hierarchical approach makes it easy to understand and effectively communicate software architecture.

The C4 L1 diagram does not contain implementation details of the system you are developing; everyone, should be able to understand it.

The C4 L2 diagram is a "zoom in" into your system (in this example, the Internet banking system).

You can create the diagrams directly in your Figma file.

Pro tip: If you want diagrams like the ones shown above, use https://uml.bigger.systems/ and write PlantUML.

Here's a template to get you started:

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(PersonaA, "Persona A", "Description of this persona")
Person(PersonaB, "Persona B", "Description of this other persona")

System_Boundary(MySystem, "My System Name") {
    Container(UI, "My System UI", "React with TypeScript", "Provides interface for the smart contract")
    Container(API, "My System's API", "Nest.JS with TypeScript", "The API for My System")
    ContainerDb(Database, "My System's Database", "PostgreSQL", "Stores data for my system")
    Container(AdminPanel, "My System's Admin Panel", "React with TypeScript", "Allows administrators to manage my system")
    
    Rel(PersonaA, UI, "Uses")
    Rel(UI, API, "Sends data and requests to")
    Rel(PersonaB, AdminPanel, "Uses")
    Rel(AdminPanel, API, "Sends requests to")
    Rel(API, Database, "Reads from and writes to")
}

Container_Ext(Soroban, "Soroban", "External Service", "Smart Contract Platform")

Rel(UI, Soroban, "Invokes and reads smart contracts")
Rel(API, Soroban, "Deploys smart contracts")

@enduml

The code above parsed by https://uml.bigger.systems/ turns into this diagram.

Examples

Find real examples from winning SCF applications from which to draw inspiration.

Soroswap.finance - Automated liquidity protocol

Soroswap is an automated liquidity protocol

FX Swap - Hedging Financial Protocol

Mykobo - EURC Anchor

Mykobo is an EURC Anchor

phoenix-contracts/docs/architecture.md at main · Phoenix-Protocol-Group/phoenix-contractsGitHub

Phoenix DEX Smart Contracts architecture