← Portfolio · Article · Methodology

How I work: ODD, hexagonal architecture, DDD, SRP and DRY

I write software with AI agents every day. That doesn't mean the AI makes the decisions: it means I have to be stricter about process and architecture, because an agent writes fast and also makes mistakes fast.

Mauro José Ciappina · 10 min read · Real code: UNNA is public and every block links to its lines on GitHub; laburo and Mr.Mauroo Studio are private, and the healthtech work is under NDA

01ODD: my daily workflow

I work with ODD (Organic Driven Development), a workflow I run on top of Gentle Shell. Every request, small or large, goes through the same steps:

1. Authorize and understand.I separate whether the request is a change or a question. If a product decision is missing, I ask a single question and wait for the answer.
2. Explore before proposing.I read the code I'm going to touch and the project memory in Engram: past decisions, bugs already fixed, conventions.
3. Size the work.If someone could finish the task with just the request and the diff, it's small and I do it directly. If not, it's large and gets a document.
4. Write the feature document.In odd/tasks/: specs that quote the original request verbatim, one task per line with its commit, and a log with every decision and every piece of evidence.
5. TDD, task by task.First the failing test, then the code. When tasks are independent, I split them across agents with allowed files that don't overlap.
6. Verify according to risk, then close.If it touches security, data or contracts, an independent verifier runs. I close with small commits and a report of what was tested and what wasn't.

02Hexagonal architecture

The domain, meaning the business rules, sits at the center and knows nothing about the outside world. Everything that is infrastructure (HTTP, database, Gmail, Mercado Pago, an LLM) comes in or goes out through a port: an interface defined by the domain. The concrete implementations are adapters that plug into that port.

In laburo the service doesn't know about Gmail or Telegram; it knows these interfaces:

type Source interface {
	Name() string
	Fetch(ctx context.Context, now time.Time) ([]core.Job, error)
}

type Mailer interface {
	Send(ctx context.Context, raw []byte) (string, error)
}

GetOnBoard, Telegram and the LinkedIn search through Exa are Source adapters. In the tests, each one is replaced by a five-line fake, which let me test rules like "never the same job twice" or "only postings with an email" with no network and without sending a single email.

export interface FiscalAuthorizerPort {
  /** Last number ARCA authorized for (issuer, point of sale, type); 0 when none. */
  lastAuthorizedNumber(issuerCuit: string, pointOfSale: number, receiptType: FiscalReceiptType): Promise<number>;
  /**
   * Requests a CAE. Rejections come back as `approved: false`; transport failures (timeouts,
   * ARCA unavailable) throw, so the caller can keep the receipt as a retriable draft.
   */
  authorize(request: FiscalAuthorizationRequest): Promise<FiscalAuthorizationResult>;
}

// Turns plan.json text into a Plan, or the JSON/schema issues that stop it.
export interface PlanParser {
  parse(text: string): ParsedPlan;
}

// plan.json text -> domain Plan through the LinkedIn Zod schema.
export class ZodPlanParser implements PlanParser {
  parse(text: string): ParsedPlan {
    return parseWith(LinkedinPlan, text);
  }
}

03DDD: the language of the business leads

Domain-Driven Design means modeling software with the language and the boundaries of the business. I use three concrete tools:

Bounded contexts

On the healthtech platform I split authentication, consent and clinical records into their own contexts inside a modular monolith. Each one has its own rules and data; they communicate through contracts, not shared tables.

In Mr.Mauroo Studio every part of the business is a context with its own domain/, application/, ports/ and infrastructure/: planning, critic, render, publishing, music, research… 42 contexts that talk to each other through ports.

Aggregates that protect consistency

In UNNA, the business with its branches is an aggregate: every change goes through it and is saved inside a row lock in PostgreSQL. That way, two concurrent edits can't delete a branch that was just created.

  /**
   * Runs work holding a row lock on the business, so concurrent edits apply one after another over
   * fresh data; the save it hands out writes inside that lock. The business is null when missing.
   */
  withBusinessLock<T>(
    businessId: string,
    work: (business: Business | null, save: (business: Business) => Promise<void>) => Promise<T>,
  ): Promise<T>;

Value objects

A business name or an amount is not a loose string or number. In UNNA the business name is normalized to Unicode NFC when it is created, and money is handled in minor units, so nobody compares or rounds incorrectly somewhere else in the code.

public static create(value: string): BusinessName {
  if (!value || !value.trim()) {
    throw new Error('Este campo es obligatorio');
  }

  // Stored composed (NFC), so the same name typed with separate accent marks is equal.
  const trimmed = value.trim().normalize('NFC');

public static fromCents(amount: number, currency: Currency = 'ARS'): Money {
  if (!Number.isInteger(amount)) {
    throw new Error('Monto en centavos debe ser un entero');
  }

04SRP: a single reason to change

Each module has one responsibility. If I need the word "and" to describe a class, I split it. In my stack that translates to:

// The channel's numbers, read the way `mrm youtube stats` reads them.
export interface ChannelStatsSource {
  readonly handle: string;
  // An OAuth client is set; says nothing about the Keychain token.
  configured(): boolean;
  // Rejects with ChannelNotConnected when the owner must connect the channel.
  fetch(): Promise<ChannelStats>;
}

05DRY: one source for each piece of knowledge

DRY isn't "never repeat a line": it means every business rule has a single source. I extract when the same logic shows up in three places and changes at the same pace; if two duplicates evolve separately, I leave them alone.

// keepPost accepts a fresh Spanish post for a fully remote, non-senior
// dev role that carries a contact email.
func keepPost(title, text, email string, posted, now time.Time) bool {
	remote := remoteRe.MatchString(text) && (fullyRe.MatchString(text) || !onsiteRe.MatchString(text))
	return email != "" && core.IsFresh(posted, now) && remote && devTitleRe.MatchString(title) &&
		match.IsSpanish(text) && match.SeniorityFits(title, "")
}

// It passes only when every score is >= PASS_SCORE and no banned default
// is left; otherwise the 3 worst are fixed first and the critique runs again.
export const PASS_SCORE = 8;
export const WORST_COUNT = 3;

06When I don't use them

These principles have a cost: more files, more interfaces, more tests. I apply them where they pay off.

• A one-off script or a prototype to validate an idea gets no ports or layers.
• A small task that can be understood from the request and the diff goes straight through: no document, no agents.
• I don't extract an abstraction for two uses that will change for different reasons.
• I don't write tests for documentation or configuration; there I verify another way and write it down.

The underlying idea is simple: AI gives me speed, and architecture and process give me control. Together, they are what let me ship products that can be maintained.