Skip to content
    All guides

    Forward Deployed Engineer

    The Integration Design Note, and When Java Wins

    Write the integration design note for the capstone service with a template and worked example, and decide when a Java and Spring AI service beats Python.

    By Published 5 min read

    Share

    This lesson is part of Forward Deployed Engineer: Integrate and Ship. Enroll for free, then sign in, to read it in full.

    Enroll to unlockAlready enrolled?

    What you'll learn: how to turn the module's decisions (placement, identity, boundary reliability) into one short design note a customer can approve, and when a Java and Spring AI service beats a Python one.

    At a glance

    Figure 1. The integration the note describes

    The deliverable: the sales portal calls the Python AI service through the gateway, with an identity provider issuing tokens and a model provider outside the estateClient app to API gateway (bearer token); Identity provider to API gateway (keys); API gateway to Python AI service (same token); Python AI service to Idempotency store (key and replay); Python AI service to LLM provider (model call)PRIVATE NETWORKClient app: sales portalClient appsales portalIdentity provider: real tokensIdentityproviderreal tokensAPI gateway: authn, limitsAPI gatewayauthn, limitsPython AI service: authz, deadlinesPython AIserviceauthz, deadlinesIdempotency store: sharedIdempotencystoresharedLLM provider: outside the estateLLM provideroutside theestatebearer tokenkeyssame tokenkey and replaymodel call

    How to read this: draw this first; the warning-coloured store is in memory only today.

    • The note records decisions, owners and open questions, not code.
    • Spring AI fits a feature inside a Spring Boot service you already run.
    • Python fits work that needs its tooling or its own releases.

    Scenario

    Composite scenario, not a real company. Lumen Industrial Supply, the fictional distributor, agrees to a pilot. The security lead wants one document first: where the service sits, how identity arrives, what happens on failure, what is unproven. The quote team asks why it is not a Spring AI feature. Numbers are illustrative.

    What you will be able to do

    • Fill the ten-section integration design note.
    • Mark each statement as evidence or an open question.
    • Use a decision tree to choose between Python and Spring AI.

    Prerequisites

    Where the Python service sits, Passing identity, Timeouts, retries, idempotency and Spring AI overview.

    Core ideas

    The note, section by section

    Each section points to evidence: the contract cites /openapi.json, identity and reliability cite the last two lessons' tests, failure behaviour a caller test, observability a sample log line. No evidence: open question.

    A template

    INTEGRATION DESIGN NOTE: <service name>, <date>, <author>
1 Purpose and scope: <use case; callers; out of scope>
2 Placement: <A direct | B via service | C via service>; reason: <one sentence>
3 Contract: <OpenAPI file and version>; error shape: <fields>
4 Identity and tenancy: <who verifies the token, where; role to action map; tenant source>
5 Boundary reliability: <deadline per layer; retry owner; key rule; sync or async and why>
6 Data and egress: <what leaves the estate; to which provider; what is not sent>
7 Failure behaviour: <per caller: what the user sees when the service is down>
8 Observability: <trace id; fields logged; fields never logged>
9 Open questions: <question | owner | date>
10 Decision requested: <approval | approver | date>

    When Java and Spring AI win

    Figure 2. Choosing the stack

    flowchart TD accTitle: Choosing the stack accDescr: Start by asking whether the AI feature is part of a Spring Boot service the team already runs. If not, a separate service is likely, and Python is the default. If yes, ask whether Spring AI covers the needs such as chat, tools, structured output and retrieval. If it does, build it in that service. If not, or if the AI part needs its own release cycle or Python libraries, run a separate Python service. A["Is the AI feature part of a Spring Boot service you already run?"] -->|no| P["Separate service: Python by default"] A -->|yes| B{"Does Spring AI cover the needs?"} B -->|no| P B -->|yes| C{"Does the AI part need its own release cycle or Python libraries?"} C -->|yes| P C -->|no| J["Build it in the Spring Boot service with Spring AI"]

    How to read this: Java wins only when all three answers point inward.

    As of 2026-11-02 the Spring AI reference lists a portable API over several model providers, tool calling, mapping of model output to Java objects, retrieval and memory support, observability and MCP integration, and shows version 2.0.2 as current.

    My default is a separate Python service, because the AI part changes faster than the transactional core. I would choose Spring AI in the quote service for a small need (extract fields, summarise, one tool) where a new runtime would trigger a security review.

    Worked example

    Assumptions: illustrative; Lumen's pilot has 8 sales engineers; the capstone is the service.

    1 Purpose and scope: product discovery for 8 sales engineers; read-only; no quote creation.
2 Placement: A, direct route behind the gateway; reason: the portal shows the answer as is.
3 Contract: OpenAPI file from /openapi.json, version v1; one error shape with a trace id.
4 Identity and tenancy: gateway verifies the token, the service verifies it again; role and
  tenant come from the token only; dev token replaced by the identity provider before the pilot.
5 Boundary reliability: deadlines 30 s gateway, 25 s portal, 10 s model call; the portal
  retries once, with an Idempotency-Key per user action; sync, because the model call is expected to take a few seconds (unmeasured, see 9).
6 Data and egress: request text and retrieved passages go to the model provider; request text may
  contain personal data and nothing filters it yet (see 9); provider terms to be checked by Lumen's security lead.
7 Failure behaviour: the portal shows "assistant unavailable" and keeps plain search working.
8 Observability: trace id on every response; request text length is logged, request text is not.
9 Open questions: shared idempotency store before more than one replica (platform, owner and
  date to be agreed); real provider behaviour is unmeasured (author); the portal fallback in 7 has no test (portal team).
10 Decision requested: approve placement A and the pilot with 8 users (security lead, date).

    Two things the capstone does not do yet appear as open questions:

    • The idempotency store is in memory, so one replica only until a shared store exists.
    • The real model adapter has never run against the live API, so quality is not a number.

    For the quote team: the feature is not in the quote service, needs retrieval with access control and an evaluation set, and changes weekly, so the tree points to a separate Python service. For email-to-fields extraction, Spring AI would win.

    In the interview: asked "why not use Spring AI?", treat it as a real option: say when it wins and how your choice follows from the customer's constraints.

    Practice task

    Write the integration design note for the capstone.

    1. Fill all ten sections of the template, using the worked example as a model.
    2. Mark each statement as evidence, or as an open question with an owner and date.
    3. Read it as the security lead; write two questions it does not answer.

    Explain it back. Tell the quote team in three sentences why the copilot is a separate Python service. A good one answers the tree's three questions and what would change your mind.

    Exercise

    Apply the decision tree to (a) a Spring Boot claims service that must extract six fields from an uploaded email, and (b) a product copilot for a new portal with a weekly changing evaluation set.

    Acceptance criteria:

    • Each case answers all three questions of the tree.
    • Each decision names one thing that would change it.

    Done when a colleague who prefers the other stack sees which answer would alter the result.

    Hint 1: answer the questions in order

    Answer each, with a reason.

    Hint 2: what would change it

    Find the answer closest to flipping, such as "Spring AI covers the needs".

    Common mistakes

    • A note that describes code. The reader needs decisions.
    • Claims without evidence. "Secure" is not evidence; a test is.
    • Hiding open questions. The reviewer will find them.
    • Choosing the stack by habit. Answer the three questions.

    Knowledge check

    1. Why must every statement be evidence or an open question?

    A reviewer cannot approve a claim they cannot check. An open question with an owner shows you know the gap.

    2. Why does the note ask for one replica only until a shared store exists?

    The store is in memory and per process. With two replicas, a retry may reach one that never saw the key and rerun the work.

    3. When does the decision tree send you to Spring AI?

    Only when the feature belongs to a Spring Boot service you already run, Spring AI covers the needs, and the AI part needs neither its own releases nor Python libraries.

    4. Why is a separate Python service the default here?

    The AI part changes faster than the transactional core.

    5. What does section 7, failure behaviour, protect the customer from?

    A user left on a broken screen. Writing down what each caller shows makes failure a designed state.

    You can now

    • Fill the ten sections of the integration design note.
    • Mark each statement as evidence or an open question.
    • Apply the three-question tree to choose Python or Spring AI.

    Further reading

    Last verified: 2026-11-02

    Next

    This is the last core lesson of module M5. The next module covers evaluation: Build a golden set

    Enroll to keep reading

    Lesson 4 of 5 · Forward Deployed Engineer: Integrate and Ship

    Write the integration design note for the capstone service with a template and worked example, and decide when a Java and Spring AI service beats Python.

    In the rest of this lesson

    • Worked example
    • Practice task
    • Exercise
    • Common mistakes
    • Knowledge check
    • You can now

    Enrolling is free. It unlocks every lesson in Forward Deployed Engineer: Integrate and Ship, tracks your progress across devices and keeps your quiz scores. The newsletter is optional.

    EnrollSign in

    Ask about this article

    Get answers grounded in this post. AI-generated — based on this article, and may be imperfect.

    Forward Deployed Engineer: Integrate and Ship· Page 4 of 5
    PreviousTimeouts, Retries, Idempotency; Sync or AsyncNext Ship the AI Service into a Customer's Environment
    Scaled AI Weekly

    Enjoyed this? Get more like it every Monday.

    Real architecture decisions, LLMOps patterns that survive production, and engineering leadership advice — from 12+ years of building at enterprise scale. Free. No spam. Unsubscribe anytime.

    Get new articles by email

    Free. We email a confirmation link first, and you can unsubscribe from any email.

    Join engineers building production AI systems

    Comments

    Back to all guides