Day 4 Summary Codex AI Architect Technical Design

Day 4. Technical Design (API Design and Interface Definition) Course Summary

Key summary of a modern collaborative interface architecture: write an API Contract — the promise linking planning and development — from the requirements doc and screen spec, find mismatches and gaps between docs, and automate impact analysis on UI and API and testing when things change.

Part 1. Background
Part 2. Lab goals
Part 3. Follow along
Part 4. How it works
Part 5. Teaching guide
Part 6. Final Task

Bottlenecks in technical design

In real projects, misunderstandings between planning, design and development lead directly to missing database items and broken consistency. Let's see why guaranteeing consistency at the design stage matters.

Understanding gap

When fields in the planning docs or screen design differ from the deployed API Spec, defects pile up: communication errors, or values that don't show on screen.

Vocabulary gap

When front-end and back-end developers define fields only by spoken agreement, names (Camel vs Snake Case) or formats don't match and they keep having the same meetings.

Sharing gap

Even when one business requirement like pricing or order steps changes, it costs a lot of analysis to see what must change in the linked APIs, front-end screens and even test code.

ChatGPT vs Codex Client (Workspace-based)

Compare ChatGPT, limited to a single chat context, with Codex Client, which understands the whole folder structure and dependencies between files.

Compared ChatGPT (general chat AI) Codex Client (Workspace-based AI)
Context awareness Cross-checks actual field mapping and feature fit between the plan, screen design and back-end API spec files Traces attributes across plan-screen-API outputs to catch gaps like missing ratings and error codes from every angle
API mismatch detection Just roughly puts together a one-off API code template Recommends consistent standard names and DB column names based on the project term dictionary
Impact analysis Suggests isolated schema errors or made-up table fixes Works backward from small schema changes (e.g. adding a column) to list API specs and screen parts to fix

Summary of today's final outputs

The list of final outputs learners create during the Day 4 session, and the purpose of each.

Task 01. Data structuring

A Mermaid ERD script and spec rendering entities and relationships pulled from a natural-language plan (output: erd-schema.md)

Task 02. API mismatch detection

A project standard term dictionary defining scattered planning terms as standard English columns (output: project-glossary.md)

Task 03. API change impact analysis

A change impact analysis listing API and screen fixes for adding booking approval (WAIT_APPROVE) (output: change-impact-report.md)

Mission 01. Design record

A Design Decision Log (DDL) archiving the reasons for normalization and data design decisions and rejected alternatives (output: design-decision-log.md)

Mission 02. API test scenarios

An Edge Case analysis report with DB improvements for concurrent payment errors, data lost on account deletion (referential integrity) and transaction rollback (output: edge-case-analysis.md)

Input / Output data pipeline

A mapping of the inputs used in the lab and the outputs produced through Codex Workspace reasoning.

01
Data structure
02
Terms
03
Change impact
M1
Decisions
M2
Exceptions
Task 01. API contract generation
šŸ“„ Input (planning meeting notes)
• day4_meeting_notes.md (meeting notes) - User flow scenarios and booking process as unstructured prose
Codex Workspace āž”
šŸ’¾ Output (ERD spec)
erd-schema.md with Mermaid ERD code - Visualizes Primary Key/Foreign Key relationships of the User, Expert, Reservation and Payment entities

STEP 1. Task 01 - API contract generation

Enter the meeting scenario prose and derive precise normalized relationships (1:N, 1:1) and Mermaid code.

šŸ” Codex request prompt (data structuring)

Based on the provided requirements doc and screen spec, list the APIs needed, define the types and English variable names of Request and Response fields, and write a standard API Contract.
  • Check that the PK and FK settings for the 4 entities User, Expert, Reservation and Payment don't conflict with the scenario logic.
  • Check that cardinality notation is correct when the Mermaid diagram (`erDiagram`) renders.

STEP 2. Task 02 - API mismatch detection

Compare the gap between Figma plan terms and DB dev specs and build a domain term master dictionary.

šŸ” Codex request prompt (term dictionary)

Cross-check the provided day4_requirements.md, day4_screen_definition.md and day4_api_specification_v1.md, find API endpoints and fields that don't match or are missing from the planning requirements or screen UI design, and write a review report.
  • Check that standard English names and column types that fit the business domain are given correctly.

STEP 3. Task 03 - API change impact analysis

Find the API and table impact when the release plan changes to add an 'approval' step to booking.

šŸ” Codex request prompt (find impact)

Analyze the provided API change request (day4_api_change_request.md), list the other system areas and docs affected when the booking request API changes, and write an API impact analysis teammates can act on right away.
  • Check that it detected the chain impact of the Reservations table status change, new API specs and button state transitions on the planned screens.

STEP 4. Mission 01 - API review and improvement

Log the rejection reasons and agreements for normalization decisions, splitting booking history physically, and so on.

šŸ” Codex request prompt (decision record)

Review the API spec in the provided day4_api_specification_v1.md, analyze improvements based on REST API design standards (HTTP Method use, URL naming), a consistent error handling structure and scalability, and write an API review report.
  • Check that the reason for splitting the history table (DEC-003) and the alternative (slower performance with one table) are clearly logged.

STEP 5. Mission 02 - API test scenarios (Edge Case)

Audit system weak points to prevent referential integrity violations (account deletion) and broken transactions.

šŸ” Codex request prompt (derive Edge Cases)

Based on the currently defined booking and payment API specs, write API test scenarios and a check list covering the normal registration flow (Happy Path) and all exception cases, like missing required parameters, wrong date formats, over-limit and expired permissions.
  • Check the plan to keep referential consistency with Soft Delete (logical delete) and the response to distributed transaction rollback.

How It Works & Key Mechanisms

Schema-aware reasoning

Going beyond simple text matching, it understands entity referential integrity (FK) and transaction lifecycles, and works backward from a natural-language plan to DDL (Data Definition Language) queries and state machine rules automatically.

Meta term clustering

It groups differently written terms (customer name vs Nickname) by meaning (Clustering) to produce a company-wide term master dictionary, and syncs the data dictionary's consistency based on it.

How the five Tasks/Missions work together in technical design

See how data and analysis from each step go around the technical design loop to maximize quality.

[API interface contract] (Task 01. Derive specs)
ā–¼
[Check plan-API mismatches] (Task 02. Consistency audit)
ā–¼
[Auto-trace design change ripple effects] (Task 03. Impact management)
ā–¼
[Improve REST architecture quality] (Mission 01. Structure review)
ā–¼
[Happy/Sad Path test coverage] (Mission 02. Scenario defense)

This interface checking pipeline removes all errors and design contradictions before a single line of code is written, giving high interface quality so the front end and back end integrate successfully on the first try.

šŸ’” Course design specs

  • Difficulty: ā˜…ā˜…ā˜…ā˜…ā˜† (advanced - includes database normalization and distributed transaction concepts)
  • Lab time: 1h 30min ~ 2h (combined design lab)
  • Real-world use: ā˜…ā˜…ā˜…ā˜…ā˜…

Learner questions/discussion topics

Topics that work well for class discussion or interview questions.

Q1. Account deletion strategy

"Between always returning HTTP Status 200 OK on errors with a detailed error code in the body (Custom Error) and using standard HTTP Status codes (4xx, 5xx), what are the pros and cons from a microservice architecture (MSA) view?"

Q2. Terminology Debt

"If a project runs to the middle without checking API mismatches, how does the resulting 'terminology debt' inside the dev team affect the real schedule?"

Final course Task for the planning/design stage

An overview of all the lab tasks and missions covered on Day 4.

Task Topic How AI is used
Task 01 API contract generation Analyze the plan and screen design to automatically derive a RESTful API contract spec
Task 02 API mismatch detection Automatically catch mismatches between planning specs and API specs (like a missing rating) and generate a report
Task 03 API change impact analysis Trace the chain impact on screens and specs to update when API parameters or states change
Mission 01 API review and improvement An API Review Report with improvements standardizing noun URLs, error code schemas and more
Mission 02 API test scenarios Derive an exception test matrix covering not just normal flows but missing required keys and format errors
← Enter Day 4 Classroom View full roadmap