AWS SSO Google Workspace Sync
This skill provides development guidelines and architectural patterns for working with the idp-scim-sync project, which keeps AWS Single Sign-On (SSO) groups and users synchronized with Google Workspace directory.
What This Skill Does
Guides development on a Go-based application that synchronizes identity provider (Google Workspace) data with AWS SSO using the SCIM protocol. The project implements an MVC-style architecture with clear separation between core business logic, data models, repositories, and provider-specific conversions.
Architecture Overview
The application follows a Model-View-Controller pattern with these key components:
**Core**: Business logic (`internal/core`)**Config**: Application configuration (`internal/config`)**Model**: Data structures and entities (`internal/model`)**Repository**: Data access layer for database operations (`internal/repository`)**IDP Conversion**: Google Workspace integration glue (`internal/idp/`)**SCIM Conversion**: AWS SCIM API integration glue (`internal/scim/`)Development Instructions
When working on this codebase:
1. Language and Framework Standards
Use **Go 1.24+** with the standard libraryLeverage Go's built-in testing package for all testsUse `make` with the provided Makefile for build, test, and run operationsManage dependencies with Go modulesUse `slog` package for all logging operationsDocument code with GoDoc conventions2. Project Structure Navigation
The codebase is organized as:
```
cmd/
├── idpscim/ # Main application entry point
└── idpscimcli/ # CLI tool for AWS and Google Workspace operations
internal/
├── config/ # Configuration management
├── core/ # Business logic
├── model/ # Data structures
├── repository/ # Database layer (PostgreSQL)
├── idp/ # Google Workspace integration
└── scim/ # AWS SCIM integration
pkg/
├── aws/ # AWS SDK wrappers
└── google/ # Google Workspace SDK wrappers
```
3. Code Style Requirements
Follow these Go style guides strictly:
[Go Style Guide](https://google.github.io/styleguide/go/guide)[Go Style Decisions](https://google.github.io/styleguide/go/decisions)[Go Style Best Practices](https://google.github.io/styleguide/go/best-practices)[Effective Go](https://golang.org/doc/effective_go.html)**Key principles:**
Use meaningful, idiomatic names for variables, functions, and packagesKeep functions small and focused on a single taskAdd comments to explain complex logic or architectural decisionsImplement dependency injection for services and repositories to facilitate testing4. Testing Strategy
Implement comprehensive tests following these guidelines:
```go
// Write unit tests with test tables
func TestFunctionName(t *testing.T) {
tests := []struct {
name string
input InputType
expected OutputType
wantErr bool
}{
// test cases
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// test implementation
})
}
}
```
**Test commands:**
`go test` - Run all tests`go test -cover` - Check code coverage`go test -race` - Detect race conditions`go test -bench` - Run benchmarks`go test -v` - Verbose output`go test -run <pattern>` - Run specific tests`go test -short` - Run short tests only5. Build and Deployment
Use the Makefile for all build operations:
Build targets are defined for both `idpscim` (main app) and `idpscimcli` (CLI tool)Output binaries are placed in `build/` directoryDocker support available via DockerfileCI/CD managed through GitHub Actions6. Integration Patterns
**Google Workspace Integration:**
All Google Workspace logic resides in `pkg/google/`Conversion layer in `internal/idp/` bridges core logic with Google APIsUse dependency injection for Google Workspace clients**AWS SCIM Integration:**
AWS SCIM logic in `pkg/aws/`Conversion layer in `internal/scim/` bridges core logic with AWS SCIM APIsFollow AWS SDK best practices for API calls7. Database Operations
Use PostgreSQL for data persistenceRepository pattern in `internal/repository/` handles all database operationsKeep business logic separate from data accessUse transactions where appropriateExample Usage
When adding a new feature to sync additional Google Workspace attributes:
1. Define the data model in `internal/model/`
2. Implement repository methods in `internal/repository/`
3. Add core business logic in `internal/core/`
4. Create IDP conversion logic in `internal/idp/`
5. Implement SCIM conversion in `internal/scim/`
6. Write comprehensive unit tests with test tables
7. Update documentation in `docs/`
Important Constraints
Always use dependency injection for testabilityNever bypass the repository layer for database accessMaintain clear separation between IDP-specific and SCIM-specific codeFollow the MVC pattern consistentlyEnsure all public functions have GoDoc commentsWrite tests before or alongside implementation (TDD recommended)Use `slog` for all logging - no fmt.Println in production codeAdditional Resources
Refer to documentation in `docs/`:
Configuration.md - Application configurationDevelopment.md - Detailed development setupAWS-SAM.md - AWS SAM deploymentDemo.md - Usage demonstrations