TheArchitect

We turn a team’s messy whiteboard into explainable, deployable cloud infrastructure - powered by Codex and grounded in the people, decisions, and intent behind it.

Comment

Inspiration

Every software product starts with people who understand the problem.

A warehouse manager understands fulfillment. A clinician understands patient workflows. A business owner understands the customer. A security engineer understands risk. But when it is time to build the system, their knowledge is handed off through meetings, screenshots, diagrams, tickets, and documents before finally reaching the engineers responsible for the infrastructure.

Important context gets lost at every step.

The original whiteboard becomes outdated. Architecture decisions disappear into chat messages. Nontechnical stakeholders cannot tell whether their requirements were interpreted correctly. Engineers spend hours reconstructing business intent before they can begin implementing the system.

Existing cloud tools generally start too late. They assume users already know which services, databases, networks, and deployment configurations they need.

We built TheArchitect to begin earlier—when the team is still deciding what the product should become.

TheArchitect creates one collaborative path from:

Business idea
→ shared whiteboard
→ team agreement
→ cloud architecture
→ infrastructure code
→ deployment

Our goal is not to replace architects or engineers. It is to help every member of a team contribute their expertise, make AI-generated decisions transparent, and preserve the human intent behind the final infrastructure.

What it does

TheArchitect is a multiplayer, AI-powered architecture workspace where technical and nontechnical teams design cloud products together.

A team can sketch its product workflow in plain language, collaborate in real time, and agree when the idea is ready. Our system then interprets the shared whiteboard, transforms it into a structured cloud architecture, explains what the AI inferred, and uses Codex to move the approved design toward deployable infrastructure.

Collaborate on a shared whiteboard

Users can create a workspace, invite teammates, choose individual cursor identities, and brainstorm together in real time.

Instead of beginning with technical services, the team can describe the system using concepts everyone understands:

Customer
→ uploads a document
→ employee reviews it
→ approved file is stored
→ customer receives an update

Participants can also add business and operational requirements such as:

  • Files contain private information.
  • Uploads must not be lost.
  • Traffic increases before deadlines.
  • Every approval must be recorded.
  • The first release should remain affordable.

This allows product managers, operations teams, industry specialists, designers, engineers, and security reviewers to contribute to the same system design.

Turn a sketch into a structured architecture

When the team is ready, participants vote to move forward.

TheArchitect captures the whiteboard and uses multimodal AI to interpret its components, labels, relationships, and constraints. Rather than returning another image or a generic paragraph, it produces structured infrastructure intent that can be validated and rendered as an editable cloud-resource graph.

A rough workflow can become an architecture containing:

  • Application entry points
  • APIs and compute services
  • Databases and object storage
  • Queues and event-processing components
  • Public and private networking
  • Security boundaries
  • Monitoring and notification services

The result preserves the speed of whiteboarding while introducing the structure required for implementation.

Make AI decisions explainable

AI-generated infrastructure can be dangerous when users cannot tell what the model assumed.

TheArchitect distinguishes among:

  • Explicit components directly represented by the team
  • Required infrastructure inferred because the system cannot operate without it
  • Optional improvements recommended for security, reliability, scalability, or cost

Review the design with an AI architect

The team can discuss the generated architecture with an AI architect directly inside the workspace.

Users can ask:

  • Why was this service added?
  • What happens if this component fails?
  • Which resources contain sensitive data?
  • Can this architecture support more users?
  • Can we simplify it for an MVP?
  • Where could operating costs increase?
  • What security controls are missing?

The assistant can explain the system in business language or propose structured modifications to the graph.

Our system keeps people in control: AI recommends and explains, while the team reviews and approves consequential changes.

Generate deployable infrastructure with Codex

Once the architecture is approved, Codex translates the structured design into implementation-ready infrastructure code.

Because Codex works from a validated architecture model rather than an isolated natural-language prompt, it receives clearer constraints, resource relationships, and deployment intent.

The generated infrastructure can then be:

  • Inspected by the team
  • Validated before execution
  • Tested in a local cloud environment
  • Exported into a development workflow
  • Prepared for deployment through AWS infrastructure tooling

TheArchitect does not stop at creating a visually convincing diagram. It connects the team’s original business intent to concrete technical output.

How we built it

Our system combines real-time collaboration, multimodal reasoning, structured graph processing, AI-assisted software development, and infrastructure as code.

Collaborative frontend

We built the user experience with:

  • React
  • TypeScript
  • Tailwind CSS
  • tldraw
  • React Flow

We intentionally use two separate visual environments.

tldraw supports flexible, freeform brainstorming where users can express ambiguous ideas without understanding cloud terminology.

React Flow displays the resulting structured architecture as typed resources and relationships that can be inspected, modified, and translated into infrastructure.

Real-time multiplayer state

We use:

  • Yjs
  • Hocuspocus
  • WebSockets

Yjs provides conflict-resistant collaborative state, while Hocuspocus synchronizes documents, participant presence, cursors, votes, and architecture updates.

This allows multiple team members to work inside the same design session without overwriting one another.

Multimodal architecture reconstruction

The reconstruction pipeline processes the whiteboard as both visual and structured context.

The model analyzes:

  • Shapes
  • Labels
  • Arrows
  • Spatial relationships
  • Business requirements
  • System boundaries
  • User annotations

It then produces a constrained architecture representation rather than unrestricted prose.

The output is validated against our supported resource schema before it becomes part of the architecture graph. This helps prevent malformed or unsupported model output from directly entering the deployment workflow.

Canonical architecture model

TheArchitect represents the generated system using structured resources and typed relationships.

The architecture model acts as the bridge among:

Whiteboard
→ AI interpretation
→ visual graph
→ architecture assistant
→ infrastructure code

This is essential because a visual diagram alone does not contain enough semantic information to generate reliable infrastructure.

Each component can include:

  • Resource type
  • Display label
  • Configuration
  • Connections
  • Security boundaries
  • Inference source
  • Explanation
  • Approval state

Codex-powered implementation

Codex helps convert the approved architecture into deployable infrastructure code and accelerates development across our codebase.

We use Codex to:

  • Translate structured architecture intent into infrastructure definitions
  • Generate and refine typed resource adapters
  • Implement frontend and backend integrations
  • Debug inconsistencies among the graph, schemas, and deployment layer
  • Produce validation and testing workflows
  • Accelerate iteration across the full-stack application

The key innovation is that Codex is not working from a vague request like “build me an AWS application.” It receives a structured, human-reviewed architecture containing explicit resources, relationships, and constraints.

Infrastructure and deployment

Our deployment workflow uses:

  • AWS CDK
  • AWS CloudFormation-compatible infrastructure
  • LocalStack for safe local testing
  • Structured deployment output and status reporting

LocalStack gives us a deterministic environment for demonstrating that the architecture can move beyond the canvas without risking an uncontrolled production deployment.

Challenges we ran into

Translating an ambiguous drawing into valid infrastructure

Whiteboards are intentionally messy.

Users may create unlabeled boxes, incomplete arrows, business concepts, external actors, duplicated components, or relationships that do not map directly to cloud services.

The model had to understand the team’s intent without inventing an unnecessarily complex architecture.

We addressed this by generating a constrained intermediate representation, validating supported resource types, and separating explicit components from inferred infrastructure.

Synchronizing multiple representations of one system

TheArchitect maintains several representations of the same product:

  • The collaborative whiteboard
  • The AI-generated interpretation
  • The structured resource graph
  • The architecture conversation
  • The generated infrastructure code
  • The deployed environment

A change in one layer can easily make the others inconsistent.

Designing a shared architecture contract was one of the most important technical challenges because every interface and AI workflow must agree on the same resources and relationships.

Building reliable multiplayer collaboration

Real-time collaboration involves much more than storing a document.

We had to synchronize:

  • Concurrent whiteboard edits
  • Participant presence
  • Cursor state
  • Team votes
  • Phase transitions
  • Architecture modifications
  • Deployment readiness

Yjs and Hocuspocus provided the collaboration foundation, but coordinating product-level state across different phases required careful design.

Using AI without hiding its assumptions

It would have been easier to send the whiteboard to a model and display whatever diagram it returned.

That would not be trustworthy.

We wanted users to understand which resources came from their original design, which resources were technically necessary, and which resources were optional AI recommendations.

Creating this distinction forced us to treat AI output as a reviewable proposal rather than an unquestionable answer.

Connecting visual design to executable code

A diagram can look correct while remaining technically meaningless.

To generate infrastructure, every node must have a supported type, configuration, relationship, and deployment mapping.

We had to move beyond visual similarity and create a graph with enough semantic structure for Codex and AWS CDK to use.

Balancing technical depth with accessibility

TheArchitect serves people with very different levels of technical experience.

Cloud engineers need precise resource information. Business participants need explanations connected to their goals.

We had to design an interface that could explain the same architecture at multiple levels without overwhelming one audience or hiding important details from another.

Accomplishments that we're proud of

We are proud that TheArchitect is not just an AI chatbot, a diagram generator, or a static infrastructure tool.

It demonstrates a complete collaborative product workflow.

During the project, we built:

  • A polished workspace creation experience
  • Multiplayer whiteboard collaboration
  • Live participant presence and cursor identity
  • Team voting and controlled phase transitions
  • Multimodal whiteboard interpretation
  • A validated cloud-resource representation
  • An editable architecture graph
  • AI-generated architecture explanations
  • Structured architecture modifications
  • Codex-assisted infrastructure generation
  • AWS CDK integration
  • A safe local deployment workflow

Our biggest accomplishment is making cloud architecture more inclusive without pretending technical expertise is unnecessary.

Domain experts can contribute the workflows and constraints they understand. AI helps translate that knowledge. Engineers retain control over validation, implementation, and deployment.

We are also proud that Codex is integrated into the core value of the product rather than added as a superficial feature. It helps bridge the approved system design and the code required to execute it.

What we learned

We learned that infrastructure code is often not the first or hardest problem in cloud development.

The harder problem is creating a shared understanding among people who view the same product from different perspectives.

A strong architecture must reflect:

  • Customer behavior
  • Business operations
  • Security requirements
  • Financial constraints
  • Failure scenarios
  • Industry knowledge
  • Technical limitations

We also learned that AI becomes more useful when it is constrained by structure.

Giving a model an open-ended prompt can produce an impressive answer, but not necessarily a reliable one. Providing typed resources, explicit relationships, supported operations, and validation rules makes the output more consistent and actionable.

Codex is especially powerful when it receives clear intent. By connecting it to a human-reviewed architecture instead of an isolated prompt, we can use it to generate code that more closely reflects the team’s actual decisions.

Finally, we learned that trust is a product feature.

Users need to know:

  • What the AI understood
  • What it assumed
  • Why it recommended a resource
  • What changed
  • What still requires a decision
  • Who approved the result

AI should not make high-impact technical decisions invisibly.

What's next for TheArchitect

Our next goal is to evolve our product from a hackathon prototype into a trusted architecture decision platform.

Architecture decision history

We want to preserve not only the final graph, but also the reasoning behind it.

Each decision could record:

  • The proposed change
  • Alternatives considered
  • Business justification
  • Technical trade-offs
  • Contributors
  • Reviewers
  • Approval status

Confidence and clarification

Future versions will identify uncertainty instead of guessing silently.

For example:

The whiteboard includes a customer-records component. Does this workload require relational queries, flexible document storage, or simple key-based retrieval?

The user’s response would guide the architecture before code is generated.

Architecture validation

We plan to add automated checks for:

  • Security risks
  • Publicly exposed resources
  • Missing encryption
  • Reliability concerns
  • Invalid network relationships
  • Deployment dependencies
  • Organizational policies
  • AWS architectural best practices

Cost-aware design

Teams should be able to compare options based on workload and budget.

An early-stage prototype should not automatically receive the same architecture as a global production platform.

TheArchitect could generate separate plans for:

  • Prototype
  • MVP
  • Growth
  • Production scale

Safe deployment review

Before deployment, the platform could show:

  • Generated infrastructure code
  • Validation results
  • Estimated cost
  • Resources being added
  • Resources being modified
  • Resources being deleted or replaced
  • Required human approvals

Role-based collaboration

Future workspaces could support formal roles such as:

  • Business contributor
  • Editor
  • Cloud architect
  • Security reviewer
  • Approver
  • Authorized deployer

This separates agreement about the design from permission to modify a cloud environment.

Development workflow integrations

We plan to connect our application with:

  • GitHub repositories
  • Pull requests
  • CI/CD pipelines
  • Issue trackers
  • Architecture documentation
  • Existing AWS environments

The approved graph could generate a pull request containing infrastructure code, documentation, validation results, and the decisions that produced it.

Most cloud tools begin after the architecture has already been decided.

TheArchitect begins with the people still deciding what the system should become—and carries their shared intent all the way to deployable infrastructure.

Built With

Share this project:

Updates