How castrozan/api-cepol-clean-code works
Project type and purpose
• This is a backend API microservice deployed as a Cloudflare Worker using Hono + Chanfana to auto-generate and validate an OpenAPI 3.1 schema.
• It implements CRUD endpoints for multiple domains (about, articles, equipments, professionals, researchs), authentication via Supabase, and image upload to a bucket.
Key layers/components (from the file tree)
• Presentation Layer (src/presentation/controllers, src/presentation/dtos)
• Application Layer (src/application/use-cases & dtos)
• Domain Layer (src/domain/entities & interfaces)
• Infrastructure Layer
• Database repositories (src/infrastructure/database/repositories)
• External services (Supabase Auth, Cloudflare bucket)
• Middleware (CORS, auth, rate limit)
• Web server/OpenAPI (src/infrastructure/web/open-api)
• Shared utilities/config (src/shared & src/env)
• Entry point (src/index.ts) and Worker config (wrangler.toml)
Architectural pattern
• Clean/Hexagonal Architecture
• Each controller calls a UseCase → operates on Domain Entities via Repository interfaces → concrete Infrastructure implementations interact with Supabase DB or bucket.
• Hono router (chanfana) sits in front to route requests, apply middleware, generate OpenAPI spec, and dispatch to controllers.
Components and relationships
a. External clients
• Browsers or HTTP clients calling REST endpoints
b. Cloudflare Worker runtime
• Wrangler-deployed edge functions executing src/index.ts
• Hono + Chanfana OpenAPI router
• Middleware (CORS, auth, rate limiting)
c. Presentation Layer
• Controllers (one per resource + upload + auth)
• Request/response DTOs
d. Application Layer
• UseCase classes (one per operation)
• Request/response DTOs
e. Domain Layer (center)
• Entities (About, Article, Equipment, Professional, Research + their Image variants)
• Repository & AuthService interfaces
f. Infrastructure Layer
• Database Repositories → Supabase (via supabaseClient.ts)
• SupabaseAuthService → Supabase Auth API
• Cloudflare bucket service → Cloudflare R2 or Images API
• OpenAPI server generator (chanfana)
g. Configuration & Utilities
• Environment loader (src/env)
• Shared error handling & validation
h. External systems
• Supabase (Postgres DB + Auth service)
• Cloudflare bucket (R2 or Images)
• Cloudflare Workers edge network
Relationships / Data flow
1. Client → HTTP request at Worker edge
2. Hono router → matching route → middleware (CORS, auth, rate limiting)
3. Controller receives request DTO → calls corresponding UseCase
4. UseCase invokes Domain logic → calls Repository/AuthService interface
5. Infrastructure implements interface → translates call to Supabase or bucket API → returns data/entities
6. UseCase returns domain entity → Controller maps to response DTO → Hono sends HTTP response
7. Chanfana auto-generates /openapi.json from controllers and DTO annotations
Putting it all together
• Inside Worker: Router + Middleware → Controllers → UseCases → Domain Interfaces → Infrastructure → External services.
• On one side, attach the auto-generated OpenAPI spec endpoint (/openapi.json).
• On another side, list shared config & utils as supporting components.