The Experiment

Could a single developer, working with AI assistance, build a scalable enterprise admin portal in three weeks? My team wanted to find out. I was chosen for the experiment.

What we set out to build:

• An admin portal with tenant management, user CRUD, role-based navigation, and a dashboard
• Frontend in Angular 20+ with a NestJS backend-for-frontend
• Nx monorepo with shared component libraries
• Authentication integration with an existing identity provider
• Internationalization infrastructure
• Real-time notifications via WebSockets

What “production-ready” meant for this experiment:

• All 40 acceptance criteria addressed (35 complete; 5 partial due to external API dependencies, portal infrastructure ready and waiting for integration)
• Zero TypeScript compilation errors, zero linting violations
• Unit tests passing across shared libraries and the BFF (CI enforced)
• CI/CD pipeline configured and running (green on main at the end of the experiment)
• Docker containerization for both frontend and backend
• Documented architecture (10 chapters of technical documentation)
• A repeatable workflow: Nx boundaries enforced, strict TypeScript mode, standardized patterns across UI and API layers

What was not in scope:

• Multi-region deployment
• Full penetration testing
• Disaster recovery setup
• Complete accessibility audit
• Performance load testing at scale

Existing infrastructure we leveraged:

• An authentication service was already deployed from a previous project (I exported its configuration and integrated with it rather than building authentication from scratch)

The “14–16 weeks traditional estimate” was a rough-sizing estimate provided by an experienced architect based on the scope and typical delivery constraints.

The Beginning: The Wrong Approach

The first three days did not go as planned.

I started with what seemed like a logical approach: give the AI the Figma screenshots and say “Build this.”

The result was not good. Layouts with misaligned components and inconsistent margins. The grid system was completely ignored. The navigation was pure static HTML, clicking on menu items did nothing. No routing, no state management, just styled dead links. Mobile did not work. Tablet was worse.

Three days into the experiment, I had something that looked vaguely like an application but would fall apart the moment you tried to use it.

Time to change the approach.

The Realization: AI Is Not Magic

After deleting everything and starting over, I had a moment of clarity. I had been treating AI as a magic wand, wave it at a problem and the solution appears.

But AI does not do magic. What AI does is amplification. It amplifies whatever you give it.

Give it vague, context-free requests? You get vague, context-free code. Give it screenshots without architecture? You get pixel-approximations without structure.

AI optimizes for plausibility given constraints. Vague constraints yield plausible junk.

Here is something else that initially bothered me: the same question, phrased identically, could produce different answers. Not wrong answers. Just different. Coming from a mathematics background where a well-posed problem has one correct answer, this felt strange.

But software engineering rarely has one correct answer. It has trade-offs. Different valid approaches exist for most problems, and the “best” one depends on constraints and context. Once I accepted this, I stopped fighting the tool and started working with it.

Practically, this led to a key habit: freeze decisions. When the AI suggested multiple plausible approaches, I would choose one, document it (an ADR-style decision note), and treat it as a constraint going forward. That’s how I kept the agent from oscillating and kept the codebase consistent.

The Turning Point: Architecture First

After those first three days, I changed everything.

Before (Failed Approach):

• Figma screenshots as the only input
• “Build this” as my prompt
• Zero technical context
• One giant prompt to do everything

After (What Actually Worked):

• Architecture documentation written first
• Phased development plan with clear milestones
• Defined technology stack and patterns
• Libraries and infrastructure before features
• Iterative conversation, building on accumulated context

Instead of asking the AI to guess what I wanted, I told it exactly what I wanted. I documented the architecture before writing a single line of code. I defined the development phases. I created the foundational libraries first, establishing patterns that would be reused everywhere.

Only then did I start building features.

Division of Labor: What I Did vs What AI Did

To be clear about who did what:

My responsibilities:

• Architecture decisions and boundary definitions
• Mapping requirements to acceptance criteria
• Code review of every generated file
• Integration validation and debugging
• Security decisions (token storage, redirect URIs, CORS)
• Risk assessment and trade-off choices
• Final approval on all patterns

What AI handled:

• Scaffolding and boilerplate generation
• Repetitive implementation (CRUD operations, similar components)
• Test generation based on specifications
• Documentation drafts
• Debugging suggestions when I hit issues
• Configuration file generation

The AI was a highly productive assistant. I remained the architect and decision-maker.

The Build: 18 Days of Real Progress

Building the Foundations

The first day after the reset was pure setup: monorepo workspace, frontend framework configuration, backend service scaffolding, styling systems, linting, formatting, git hooks. Done in about eight hours.

The next couple of days were about creating shared libraries. The atomic components that would be the building blocks for everything else. Buttons, inputs, cards, modals, the primitives. Plus all the TypeScript interfaces and contracts.

By the end of that phase, I had 8 libraries generated, 7 atomic components, 25+ TypeScript interfaces, and 69 passing tests.

Next came authentication. I exported the configuration from our existing identity provider, provided the AI with the service URL and settings, and asked it to integrate. One day later, the entire authentication flow was working, token validation, silent refresh, the complete integration.

Then the application shell: header with branding, collapsible sidebar navigation, footer, tenant selector, dynamic breadcrumbs.

One week after the reset. Base infrastructure complete.

A quick note on “scalable,” because the word is vague: In this context, “scalable” did not mean “multi-region with auto-scaling load tests.” It meant the codebase could scale in scope and complexity without collapsing:

• Nx boundaries enforced separation (apps vs libs, UI vs domain vs data access)
• Shared patterns were established early (component APIs, state approach, error handling, DTOs/contracts)
• Feature work became additive rather than disruptive
• New modules could be added without rewriting core foundations

Features and Refinement

The remaining two weeks were about building on those foundations. Dashboard with KPI cards. Activity feeds. Internationalization infrastructure. CRUD operations. Global search with keyboard shortcuts. Real-time notifications via WebSockets.

Each day had a clear objective. Each phase built on the previous one.

The 5 partial items were features dependent on backend APIs that were still being built by another team, the portal infrastructure was ready, waiting for integration.

What I Learned

1. Context Is Everything

AI without context produces code that compiles but does not work. When I gave the AI architecture documentation, development plans, and clear specifications, it produced code that fit together. When I gave it screenshots and said “build this,” I got unusable output.

2. Vague Prompts = Vague Results

“Make a login” produces something that vaguely resembles a login.

“Integrate with the identity provider at this URL using OAuth 2.0 with PKCE flow, handling token refresh silently, storing tokens in memory, and extracting roles from the token claims” produces what you actually need.

3. Sequential Phases Matter

Trying to build everything at once results in code that does not fit together. Building in phases (foundations first, then libraries, then features) means each layer builds on the last. The AI maintains context. Patterns established early propagate forward.

4. Trust, But Verify

AI sometimes generates code that compiles perfectly but does not make sense. You remain the architect. You remain responsible for the code. Review everything.

5. Adapt Rather Than Demand Perfection

It is easier to adapt a well-made component than to specify every detail upfront. When the AI generates a solid component, tweaking it takes minutes. Trying to get perfection from the first prompt wastes time.

6. You Must Teach It Your Sense of Readability

AI often defaults to patterns that are widely considered “best practice,” such as heavy file separation and strict structural purity.

That is not always what I want.

In multiple cases, I had to ask the AI to rewrite code to be more humanly readable, not necessarily more abstract or more “correct,” but easier to understand at a glance. In practice, that often meant explicitly asking it to separate concerns by splitting logic, templates, styles, and tests into their own files, instead of collapsing everything into a single file for convenience.

These decisions were not about right versus wrong. They were about taste, ergonomics, and maintainability for real humans.

AI does not have taste. It borrows it from whatever context you provide.
If you care about how code feels to read and work with, you must teach that explicitly.

7. Commit Small, Step-by-Step Improvements (Or You’ll Lose Time)

One rule I had to enforce was committing progress increment by increment.

AI can diverge quickly. If you let it make large, multi-file changes in one go, it becomes surprisingly hard to keep track of what actually changed, why it changed, and whether it violated an earlier decision or pattern. The bigger the batch, the more review becomes “trust me bro,” and that’s where mistakes slip in.

So I worked in small slices:

• one component at a time,
• one flow at a time,
• one refactor at a time,
• verify, commit, move on.

When I ignored this and got greedy, asking for too much at once, I paid for it. A couple of times, I lost one to two hours unwinding changes, restoring clarity, and re-establishing the original direction.

The takeaway: AI makes iteration cheap, but only if you keep the loop tight. Small commits keep the system understandable, the diffs reviewable, and the project aligned with the architecture.

The Quality Question

One concern I hear: “If it is so fast, the quality must be terrible.”

In this experiment, quality was higher than I expected, not because AI is magic, but because of how the workflow enforced discipline:

• Tests were written alongside the code, not deferred
• Documentation was generated as we developed
• Code consistency was higher because the same patterns repeated with fewer human-driven style variations
• Architecture was defined upfront and followed throughout

The velocity came from consistency, not from cutting corners.

That said, I would not claim “absolute quality” or “100% coverage.” What I can say: the codebase passed our team’s code review standards, the CI pipeline was green, and the acceptance criteria were addressed (with the partial items clearly identified as integration-dependent).

What This Changes

For Developers

This is not about replacement. It is about amplification. If you understand architecture, AI helps you implement faster. If you do not know what you want, AI will not save you. It amplifies your knowledge, including the gaps in it.

For Teams

The economics shift. Projects that required teams of 8 for months might require smaller teams for shorter periods. This does not mean fewer developers, it means developers can take on more ambitious scope.

For Planning

Traditional estimates may need recalibration. But be careful: AI-assisted development still requires someone who understands architecture, can review code, and can catch the gotchas. The time savings come from execution, not from skipping expertise.

A Personal Reflection

There’s a line from Limitless(2011) that stuck with me throughout this experiment:

“The pill doesn’t make you smarter. It makes you more of what you already are.”

Copilot works the same way.

It doesn’t give you judgment. It doesn’t give you architectural thinking. It doesn’t give you taste.

It amplifies whatever you bring to the table.

If you bring clear architecture, discipline, and strong fundamentals, AI multiplies their impact.
If you bring vague thinking and weak foundations, it will happily multiply those too… just faster.

That realization fundamentally changed how I approach AI-assisted development.

The Conclusion

The experiment answered the question: yes, one developer with AI assistance could deliver a functional, well-structured admin portal in three weeks.

I started this journey skeptical of tools that promised too much. I ended it with a more nuanced view: AI-assisted development works, but it works because of what you bring to it. Architecture knowledge matters more, not less. Ability to specify what you want matters more, not less. Judgment about what is right matters more, not less.

The AI is a force multiplier. Bring something real to the table (context, clarity, specifications, architectural thinking) and the results are significant. Skip the preparation, and you will spend your time debugging output that looks plausible but does not work.

The Next Phase: Teaching the Tool

The experiment proved that AI-assisted development works when constraints are clear and stable. The obvious next step is to stop relying on implicit knowledge and make those constraints explicit.

The goal is not to let AI freely generate code, but to encode architectural intent directly into the project so the tool operates inside a narrow, safe problem space.

In practice, this means turning judgment into structure:

• Architectural rules are written down and non-negotiable
• Approved patterns are documented and reused by default
• Folder structure, naming, and boundaries are enforced
• Feature work follows a predefined, repeatable path

Instead of starting from a blank prompt, feature development begins inside a constrained template that already respects the architecture.

In that model, a Business Analyst does not write code. They describe behavior and acceptance criteria within a bounded framework. Copilot generates implementation that already conforms to the system’s rules. A developer still reviews and approves, but no longer needs to hand-craft every feature from scratch.

This does not eliminate risk. Business logic is subtle, and AI can still produce plausible nonsense if boundaries are weak. But the experiment made one thing clear: AI performs best when it is not allowed to guess.

The question going forward is no longer “Can AI write code?” It is “How narrow and safe can we make the space in which it operates?”

If that space is well-defined, even partial success changes the economics: less time spent on scaffolding, more time spent on architecture, edge cases, and real complexity.

That is the direction worth exploring next.

Key Takeaways

Do:

• Document architecture before generating code
• Use sequential phases (foundations → libraries → features)
• Review every generated file
• Be specific in what you ask for
• Validate against real endpoints and documentation
• Freeze decisions when multiple valid solutions exist (document and enforce them)

Do Not:

• Try to build everything at once
• Go from designs directly to code without architecture
• Trust AI output without verification
• Use vague prompts and hope AI figures out what you mean

The numbers in this article are from a real experiment. The gotchas are real failures I encountered. The lessons are what I took away from the experience.

A story about turning 500+ pages of technical documentation into an intelligent, conversational assistant — built entirely through AI-assisted development.

The Problem: Drowning in Documentation

If you’ve ever worked on a large enterprise software platform, you know the feeling. Hundreds of architectural decision records. Dozens of API specifications. Installation guides, change logs, blog posts, and design documents scattered across folders. Each one carefully written, meticulously reviewed and almost impossible to find when you actually need it.

That was our reality.

Our documentation site had grown to include:

• ADRs (Architectural Decision Records) explaining every major technical decision
• Specifications for every feature and integration
• Installation Guides for deployment and configuration
• Change Logs documenting every release
• Blog Posts sharing team knowledge and updates

The irony wasn’t lost on us. We had invested heavily in documentation, yet developers still pinged each other on Teams asking, “Where’s the spec for X?” or “What’s the reasoning behind Y?” The knowledge was there, but finding it felt like searching for a needle in a haystack.

The Vision: A “Knower of All Things”

I had a dream. A simple one, really:

What if we could just… ask the documentation?

Not search it. Not browse it. Ask it. In natural language. Like talking to a colleague who had read every single page and remembered every detail.

I wanted an AI assistant that could:

• Answer questions about our platform in plain English
• Always cite its sources so developers could dig deeper
• Never make things up-strictly grounded to our actual documentation
• Feel like a helpful colleague, not a generic chatbot

I called this vision “The Keeper of Specs” — an AI that would be the ultimate authority on our product documentation.

How It Started: A Single Prompt

Here’s where the story gets interesting. I didn’t start by writing code. I started by talking to GitHub Copilot.

The very first prompt was deceptively simple:

“I want to add an AI chat that indexes this documentation and uses Azure OpenAI to answer questions about it”

That single sentence kicked off an extraordinary development journey. Over the course of several iterative conversations, Copilot helped me build:

1. A custom Docusaurus plugin that scans and indexes all markdown files at build time
2. A React chat component with a floating UI, markdown rendering, and source links
3. Azure OpenAI integration for intelligent response generation
4. A sophisticated search engine using TF-IDF and BM25 ranking algorithms

The entire system was built through conversation-refining, iterating, and improving with each prompt.

The Architecture: RAG to the Rescue

The solution follows a Retrieval-Augmented Generation (RAG) pattern. If you’re not familiar with RAG, here’s the core idea:

1. Retrieve the most relevant documentation chunks based on the user’s question
2. Augment the AI’s prompt with that context
3. Generate a response that’s grounded in the retrieved information

This approach solves the hallucination problem. Instead of relying on the AI’s training data (which might be outdated or wrong), we force it to answer only based on our actual documentation.

The Fine-Tuning Journey

The first version worked, but it wasn’t great. Here’s what we learned and refined:

1. Chunking Strategy: Hybrid Approach

Our initial approach indexed whole documents. The problem? Documents are too long, and context windows are limited. We evolved to a hybrid chunking strategy:

• Document-level chunks (1,500 chars) for overall context
• Section-level chunks (800–1,200 chars) for specific topics
• Overlapping windows (150–250 chars) to avoid cutting important context mid-sentence

const CONFIG = {
  docSummaryMaxChars: 1500, // Document summary
  sectionTargetSize: 1000, // Section chunks
  sectionMinSize: 300, // Minimum viable chunk
  sectionOverlap: 200, // Overlap between chunks
};

2. Search Relevance: Beyond Simple TF-IDF

Basic TF-IDF wasn’t enough. We enhanced the search with:

• BM25 scoring with tuned parameters (k1=1.5, b=0.5)
• Field weighting (titles and section headers weighted 3x higher than content)
• Synonym expansion (e.g., “performance” matches “speed”, “optimization”, “latency”)
• Fuzzy matching as a fallback for typos and variations

const fieldWeights = {
  title: 3.0, // Most important
  sectionHeader: 3.0, // Section headers are navigation targets
  keywords: 2.5, // Explicitly tagged
  description: 1.5, // Summary content
  content: 1.0, // Bulk text
  path: 0.5, // URL paths
};

3. Grounding: The System Prompt That Changed Everything

The biggest improvement came from engineering the system prompt. Early versions would confidently make up information. We fixed this with strict grounding rules:

const systemPrompt = `You are the Keeper of Specs, a documentation assistant.

## CRITICAL INSTRUCTIONS:

### GROUNDING RULES (MUST FOLLOW):
1. ONLY use information from the DOCUMENTATION CONTEXT below
2. NEVER guess or infer information not explicitly stated
3. NEVER present assumptions as facts
4. ALWAYS cite sources with document title and URL

### IF CONTEXT IS INSUFFICIENT:
You MUST respond with:
1. What specific information is missing
2. Which document would likely contain it
3. A reformulated question you could answer

### CITATION REQUIREMENTS:
- Every factual claim must be traceable to a source
- Use the exact document title from chunk metadata
- Copy URLs exactly as shown`;

This prompt engineering made the AI honest. When it doesn’t know something, it says so-and suggests where to look.

4. Response Quality: Structured Formats

We mandated a consistent response structure:

**Answer:**
[Concise answer with inline citations]

**Recommended Next Steps:** (if applicable)

- [Actionable items]

**Sources:**

- [Document Title](/path) - [what info came from here]

This made answers scannable and verifiable.

The Technical Stack

For those who want to replicate this:

The Docusaurus Plugin

The heart of the system is a custom plugin that runs at build time:

module.exports = function docIndexerPlugin(context, options) {
  return {
    name: "docusaurus-plugin-ai-chat-indexer",

    async contentLoaded({ actions }) {
      const { setGlobalData } = actions;
      // Scan all markdown in docs/, adr/, specs/, etc.
      // Extract frontmatter, split into chunks
      // Generate searchable index
    },

    async postBuild({ outDir }) {
      // Write ai-chat-index.json for production
    },
  };
};

The Document Indexer

A TypeScript class that handles runtime search:

interface DocumentChunk {
  id: string;
  title: string;
  sectionHeader?: string;
  content: string;
  path: string;
  url?: string;
  category: string;
  keywords?: string[];
  type?: "document" | "section";
};

What We Learned

1. AI-Assisted Development is Real

This entire feature was built through iterative prompting with GitHub Copilot. Not just code completion, actual architectural discussions, debugging sessions, and refinement. The AI suggested patterns I wouldn’t have considered.

2. Grounding is Everything

Without strict grounding, LLMs will hallucinate confidently. The system prompt that says “I don’t know” is more valuable than one that makes things up.

3. Search Quality Matters More Than AI Quality

Garbage in, garbage out. If your retrieval returns irrelevant chunks, the best AI in the world can’t save you. We spent more time on BM25 tuning than on Azure OpenAI configuration.

4. Chunking is an Art

Too big and you waste context window. Too small and you lose meaning. Overlapping chunks help, but there’s no perfect size-it depends on your content structure.

5. Source Citations Build Trust

Developers are skeptical (rightfully so). When every answer includes clickable source links, adoption skyrockets. People can verify, and they learn to trust.

The Result: The Keeper of Specs in Action

Today, the Keeper of Specs lives as a floating chat bubble on every page of our documentation site. Developers ask questions like:

• “How does the event error handling work?”
• “What’s the caching strategy for case loading?”
• “Who approved the multitenancy ADR?”

And they get answers-with sources. Grounded. Verifiable. Helpful.

The dream of having an AI that truly “knows” our entire product spec is now reality.

Try It Yourself

If you want to build something similar, here’s my advice:

1. Start with a clear use case. Ours was “answer questions about documentation.”
2. Use RAG, not fine-tuning. It’s simpler, cheaper, and your context stays current.
3. Invest in chunking and search. The retrieval step is more important than you think.
4. Engineer your system prompt ruthlessly. Grounding prevents hallucination.
5. Use AI to build AI. GitHub Copilot accelerated our development dramatically.

The era of static documentation is ending. The future is conversational, intelligent, and grounded.

Welcome to the age of the Keeper of Specs.

This article was written to share our journey building an AI-powered documentation assistant. The entire feature was developed using GitHub Copilot, demonstrating how AI can accelerate development while maintaining code quality and architectural consistency.

Tags: #AI #AzureOpenAI #RAG #Docusaurus #DeveloperExperience #Documentation #GitHubCopilot #MachineLearning

Pedro V. Leite is a software engineer passionate about developer experience and AI-assisted development. Follow for more stories about building intelligent tools.

The core idea is simple: use Nx to manage one repository containing many deployable apps, and enforce a symmetric library model on both frontend and backend. If you learn the UI layering once, you can apply the same mental model to NestJS features and platform code.

What this architecture is for

You should consider this approach if you expect:

• Multiple Angular applications over time (e.g., portal-a, portal-b, …)
• Multiple NestJS BFFs aligned to those portals (e.g., bff-portal-a, bff-portal-b, …)
• A shared design system and UI reuse across portals
• Shared backend “platform” capabilities across BFFs (auth, logging, error handling, caching, downstream orchestration patterns)
• CI/CD that remains fast as the repository grows (affected-only builds/tests)

The core principle: symmetry and strict dependency direction

Most monorepos fail because “shared” becomes a dumping ground. This design avoids that by enforcing:

1. Symmetric layers on both FE and BE:

• atomic: stable primitives, minimal dependencies, rarely changed
• shared: reusable composites, still generic
• projects: portal-specific composition, isolated per portal folder

2. One-way dependency flow (no cyclic or sideways imports)

That gives you scale without chaos.

Repository structure

A representative structure looks like this:

apps/
  portal-a/                 # Angular SPA
  portal-b/                 # Angular SPA
  bff-portal-a/             # NestJS BFF
  bff-portal-b/             # NestJS BFF

libs/
  # FRONTEND (Angular)
  ui-atomic/                # Immutable UI primitives
  ui/                       # Shared composite UI
  ui-projects/
    portal-a/               # Portal-specific UI composition
    portal-b/

  # BACKEND (NestJS) — same layering model
  bff-atomic/               # Immutable backend primitives
  bff/                      # Shared backend composites
  bff-projects/
    portal-a/               # Portal-specific backend composition
    portal-b/

  # CROSS-CUTTING
  shared-types/             # DTO/contracts (types-only)
  shared-utils/             # Pure utilities (env-neutral)
  design-tokens/            # Theme tokens (frontend foundation)
  api-clients/              # Typed downstream clients (backend foundation)

This is intentionally explicit. It scales because each new portal has a predictable “home” on both sides.

Frontend layers (Angular)

ui-atomic: immutable primitives

Examples: button, input, dropdown, icon wrappers, basic form controls.

• Stable API surface
• Minimal dependencies (ideally only design-tokens and minimal shared-utils)
• Changes are rare and require strong review because everything depends on it

ui: shared composites

Examples: layouts, navigation patterns, reusable widgets.

• Built by composing ui-atomic
• Still portal-agnostic
• No business logic, no portal assumptions

ui-projects/portal-x: portal-specific composition

Examples: portal-specific UI wrappers, variations, styling decisions, portal-specific layouts.

• Each portal gets its own folder
• No cross-portal imports (portal-a must not import portal-b)
• This prevents polluting shared UI with portal-specific behavior

Backend layers (NestJS) — mirrored to UI

bff-atomic: immutable backend primitives

Think “backend primitives” instead of “UI primitives”:

• base error types and error mapping building blocks
• request context primitives (correlation ID, tenant, user)
• standardized HTTP wrappers (timeouts/retries)
• foundational logging structures

Minimal dependencies, stable surface area.

bff: shared backend composites

Reusable platform modules:

• shared interceptors, exception filters
• standardized auth integration patterns
• caching wrappers
• generic orchestration helpers and response shaping patterns

Built on top of bff-atomic, still portal-agnostic.

bff-projects/portal-x: portal-specific backend composition

This is where portal-specific orchestration lives as reusable modules for that portal:

• portal-specific controllers/modules
• mapping helpers and facades
• composition of downstream calls for portal-x

Again: no cross-portal imports.

Cross-cutting contracts and utilities

shared-types (types-only)

This is your shared API contract layer:

• DTOs and enums used by portals and BFFs

Hard rule: types only. No Angular code, no Node APIs, no runtime logic.

shared-utils

Pure utilities that work in both browser and Node (no environment coupling).

api-clients

Typed downstream clients for BFFs (REST/GraphQL wrappers). Keeps orchestration consistent and testable.

design-tokens

Theme and design primitives consumed by ui-atomic. Prevents hard-coded styling constants scattered across portals.

The dependency network: one-way imports

This architecture stays scalable because imports are predictable:

Frontend

portal-x → ui-projects/portal-x → ui → ui-atomic → design-tokens

Backend

bff-portal-x → bff-projects/portal-x → bff → bff-atomic

Shared layers

• shared-types and shared-utils can be used broadly, under strict constraints
• backend libraries never import frontend libraries (ever)

In practice, these rules must be enforced by Nx tagging and lint constraints; otherwise teams will bypass them.

Why this scales operationally

Adding a new portal becomes mechanical

To add portal-c, you do not redesign architecture. You add:

• apps/portal-c
• apps/bff-portal-c
• libs/ui-projects/portal-c
• libs/bff-projects/portal-c

Everything else is shared and already governed.

Teams get clean ownership boundaries

• design-system owners maintain ui-atomic and design-tokens
• shared UI owners maintain u
• portal teams own ui-projects/portal-x
• platform/backend owners maintain bff-atomic and bff
• portal backend teams own bff-projects/portal-x

This prevents the classic “everyone touches everything” failure mode.

CI remains fast as the repo grows

Nx can run only what is affected:

• change portal-a only → build/test portal-a only
• change shared-types → build/test impacted portals and BFFs
• change ui-atomic → build/test everything that depends on it (intended)

Deployment stays simple: one repo, many deployable artifacts

Monorepo does not imply monolithic release.

• Each portal-x builds to static assets and deploys independently (CDN/object storage/Nginx).
• Each bff-portal-x builds to its own container image and deploys independently (Kubernetes/ECS/etc.).
• Libraries do not deploy; they are build-time reuse.

This keeps the operational model clean even as the repository grows.

Straight talk: trade-offs

This architecture is not “lightweight.” It buys scalability by enforcing structure.

• You must enforce boundaries, or the repo will degrade.
• ui-atomic must remain stable, or you create churn everywhere.
• shared-types must be treated as an API contract surface, or you create tight coupling and painful breaking changes.
• You get long-term velocity at the cost of upfront discipline.

Conclusion

If you want a codebase that can grow from two portals to twenty without collapsing under its own weight, this symmetric Nx monorepo model is the right foundation. It replaces ad-hoc sharing with a controlled dependency network, gives each portal a clear place to evolve without contaminating shared code, and keeps both frontend and backend understandable by using the same layering logic end-to-end.

The payoff is not theoretical: you get faster delivery as the repo grows, cleaner ownership boundaries, safer refactors, and deployability that remains straightforward because each portal and BFF is still an independent artifact. The cost is discipline — strict import rules, stable atomic layers, and contracts treated as contracts. If your team is willing to enforce those rules, this architecture won’t just scale; it will stay maintainable while scaling.