python-cola-skill

Python COLA Architecture

COLA = Clean Object-Oriented and Layered Architecture

Layered Architecture

Adapter → Application → Domain ← Infrastructure
                    ↘      ↙
                     Client

Layer	Responsibility	Python Implementation
Adapter	Receives external requests	Flask Blueprint / FastAPI Router
Application	Use case orchestration	Service, CmdExe, QryExe
Domain	Core business logic	Entity, ValueObject, Gateway interface
Infrastructure	Technical implementation	Gateway implementation, SQLAlchemy
Client	DTO definition	Command, Query, CO

Directory Structure

project/
├── adapter/routes/           # Flask Blueprint
├── application/
│   ├── command/              # *_cmd_exe.py
│   ├── query/                # *_qry_exe.py
│   └── service/              # *_service.py
├── client/
│   ├── api/                  # *_service_i.py (Protocol)
│   └── dto/
│       ├── command/          # *_cmd.py
│       ├── query/            # *_qry.py
│       └── co/               # *_co.py
├── domain/
│   ├── {aggregate}/          # entity.py, value_object.py
│   └── gateway/              # *_gateway.py (ABC)
├── infrastructure/
│   ├── gateway_impl/         # *_gateway_impl.py
│   ├── convertor/            # *_convertor.py
│   └── repository/           # models.py
└── app.py

Naming Conventions

Type	Suffix	Location
Command	_cmd	client/dto/command
Query	_qry	client/dto/query
Command Executor	_cmd_exe	application/command
Query Executor	_qry_exe	application/query
Client Object	_co	client/dto/co
Service Interface	_service_i	client/api
Service Implementation	_service	application/service
Gateway Interface	_gateway	domain/gateway
Gateway Implementation	_gateway_impl	infrastructure/gateway_impl
Convertor	_convertor	infrastructure/convertor

Core Principles

1. The Domain layer does not depend on any layer(pure Python, no framework dependencies)
2. Infrastructure implements the Gateway interfaces defined by Domain
3. The Client layer is depended on by all layers (DTO definitions)

Code Templates

For detailed code examples, please refer to:

• Response and DTO: references/dto.md
• Service and Executor: references/service.md
• Gateway Pattern: references/gateway.md
• Complete Example: references/example.md

Refactoring Checklist

1. Create the adapter/application/client/domain/infrastructure packages
2. Define Response, Command, Query, and CO classes
3. Create CmdExe/QryExe executors and Service
4. Define Gateway interfaces (ABC) and implementations
5. Create Convertor
6. Migrate routes to adapter/routes

Python vs Java Comparison

Java	Python
interface	Protocol or ABC
@Autowired	Constructor injection
@CatchAndLog	@catch_and_log decorator
@Data	@dataclass
@RestController	Flask Blueprint