• 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 monorepo was set up with the following structure:

syncraft/
├── packages/
│   ├── core/              # Entities, Use Cases, Partials
│   ├── storage/           # Browser storage adapters
│   ├── sync-api/          # Custom API gateway
│   ├── sync-gdrive/       # Google Drive gateway
│   └── sync-onedrive/     # OneDrive gateway
├── server/                # Go custom sync backend
├── client-go/             # Go client SDK
├── schema/                # JSON Schema definitions
└── Taskfile.yml           # Unified task runner

Core TypeScript Package

The core package implements Clean Architecture:

• Entities: Document, Device, Namespace, KeyRegistryEntry
• Use Cases: PullUseCase, PushUseCase, DeviceUseCase
• Partial Entities: PartialDocument, PartialDevice (in usecases/partials/)
• Interfaces: Repository interfaces for DI
• Utilities: ULID path generation, LWW merge logic

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.