• Syncraft

Initial Architecture

The first implementation phase focused on establishing the project structure and core types. This foundation will support all future development.

Project Structure

The project was set up with the following structure:

syncraft/
├── client-ts/           # TypeScript client SDK (single package)
│   └── src/
│       ├── core/        # Entities, Use Cases, Partial Entities
│       ├── persistence/ # Repository implementations
│       └── gateways/    # Sync adapters (API, GDrive, OneDrive)
├── client-go/           # Go client SDK
│   ├── core/
│   └── infrastructure/
│       └── gateways/    # Sync adapters
├── server/              # Go custom sync backend
├── schema/              # JSON Schema definitions
└── Taskfile.yml         # Unified task runner

TypeScript Client

Single package with Clean Architecture:

• Core: Document, Device, Namespace, Use Cases, Partial Entities
• Persistence: DocumentRepository, KeyRepository implementations
• Gateways: SyncApiGateway, SyncGDriveGateway, SyncOneDriveGateway

Go Client

Same structure as TypeScript, single module:

• Core: Entities, Use Cases, Partial Entities
• Infrastructure: Persistence, Gateways
• Types: Sentinel errors

Go Server Structure

The Go server follows Clean Architecture:

server/internal/
├── api/
│   ├── handlers/          # HTTP handlers
│   ├── payloads/          # Request/response DTOs
│   └── router/            # Route definitions
├── config/                # Configuration (go-envconfig)
├── core/
│   ├── entities/          # Domain objects
│   └── usecases/
│       ├── interfaces/    # Repository interfaces
│       └── *.go           # Use case implementations
├── types/                 # Sentinel errors, validation
├── usecases/
│   └── partialentities/   # PartialDocument, PartialDevice
├── infrastructure/
│   ├── persistence/
│   │   ├── embed.go       # go:embed migrations
│   │   ├── migrate.go     # Migration runner
│   │   ├── migrations/    # SQL migration files
│   │   └── sqlc/          # Repositories (*_repository.go)
│   │       ├── dal/       # Generated from queries
│   │       └── queries/   # SQL query definitions
│   └── gateways/          # External service adapters
├── registry/              # DI wiring at router level
└── shared/                # Shared utilities

Documentation

The ARCHITECTURE.md file documents all decisions:

• Data model and encryption
• File paths and bucketing
• Sync protocol and conflict resolution
• Project structure and naming conventions

The initial architecture demonstrates remarkable foresight. By establishing Clean Architecture patterns from the beginning, the codebase is prepared for growth. The parallel structure between TypeScript and Go ensures that knowledge transfers seamlessly across languages—a crucial factor for long-term maintainability.