DEV Community: Chidubem Okoli

I replaced theoretical study with high-intensity practice — and the result? I passed the AWS Solutions Architect Associate exam.

Chidubem Okoli — Wed, 07 Oct 2026 22:18:16 +0000

As I progressed through my AWS learning journey, I went from being familiar with EC2 to working with services like Lambda, IAM, VPC, RDS, DynamoDB, Aurora, and several others.

At some point, I felt I had built enough knowledge to take the AWS Certified Solutions Architect – Associate exam.

Until I decided to solve Tutorials Dojo practice questions.

That was my rude awakening.

I quickly realized that knowing AWS services was not the same as knowing how to architect solutions on AWS.

I came across Tutorials Dojo frequently while researching how other people prepared for the exam, especially through the AWS Certifications Reddit community.

NB: This Reddit community was extremely helpful throughout my preparation. If you're preparing for an AWS certification, I'd recommend spending some time going through the posts, discussions, study tips, and experiences shared there.

The exam was testing something different

The scenario-based questions weren't simply asking:

"What does this AWS service do?"

They were asking me to think through situations such as:

Which architecture best satisfies these requirements?
What is the most cost-effective solution?
Which solution provides the highest availability?
What trade-offs should I consider in this scenario?
Which service or configuration minimizes operational overhead?
Which option satisfies the requirements with the least amount of change?

That was when I realized I had to change my study approach.

I was studying AWS services.

The exam was testing whether I could use those services to make the right architectural decisions.

That changed how I approached my preparation.

I stopped studying only for knowledge and started practicing for decision-making

I went through Stephane Maarek's AWS Solutions Architect Associate course on Udemy to build and strengthen my understanding of the exam objectives and AWS services.

But I didn't stop there.

I used Tutorials Dojo extensively to get accustomed to the scenario-based nature of the questions.

I primarily used the review mode, and I developed a simple rule for myself:

Every wrong answer had to become a learning opportunity.

If I got a question wrong, I didn't just look at the correct answer and move on.

I read the explanation carefully to understand why I got it wrong.

I wanted to understand:

Why was the correct option correct?
Why were the other options wrong?
What requirement in the question eliminated the other choices?
Was I misunderstanding an AWS service?
Was I missing a key architectural concept?
Was I choosing a technically valid solution when the question was asking for the most cost-effective, most highly available, or least operationally complex solution?

Whenever the explanation wasn't enough for me, I used ChatGPT to break the concept down further and help me understand the reasoning behind the answer.

This became more important because I was trying to get better at recognizing the architectural pattern behind the question.

I also used AWS Skill Builder to supplement the other resources I already had. I didn't want to take any chances with my preparation, so I used it to reinforce areas where I felt I needed more understanding.

My preparation eventually became less about memorizing AWS services and more about understanding trade-offs, requirements, architecture, cost, availability, performance, and operational complexity.

That shift from theoretical study to high-intensity, scenario-based practice changed my preparation completely.

And eventually, it paid off.

I passed the AWS Certified Solutions Architect – Associate certification.

This is such a significant milestone for me in my Cloud and DevOps career.

Onto the next.

Also if you have any questions, don't forget to reach out to me on LinkedIn

Choosing Amazon Bedrock Managed Knowledge Bases: An Architecture Decision in My RAG Application

Chidubem Okoli — Wed, 23 Sep 2026 11:32:10 +0000

When I started designing the RAG architecture for the internal AI assistant project, one of the first decisions I had to make was:

Where should the application's knowledge live, and which component should be responsible for turning that knowledge into something the model can retrieve?

There are several ways to build a RAG system on AWS.

I could assemble and manage the retrieval components myself, use a vector database directly, or use Amazon Bedrock Knowledge Bases to manage much of the RAG data pipeline.

During the project, I explored the architecture from both perspectives before settling on an Amazon Bedrock Managed Knowledge Base.

This article explains that decision and the technical tradeoffs behind it.

The Initial Problem

The application needed to answer questions using internal company documents.

The source documents included:

Brand Guidelines
Script Bank
Caption Bank
Client Proposal Template

My initial mental model was:

Documents
    ↓
Amazon S3
    ↓
Vector Storage
    ↓
Similarity Search
    ↓
Foundation Model
    ↓
Response

But implementing that architecture means taking responsibility for considerably more than vector storage.

The complete pipeline involves:

Document ingestion
       ↓
Document parsing
       ↓
Chunking
       ↓
Embedding generation
       ↓
Vector indexing
       ↓
Metadata
       ↓
Similarity search
       ↓
Retrieval
       ↓
Context construction
       ↓
Model invocation
       ↓
Source attribution

At that point, the most important architectural question became:

Which parts of the RAG pipeline should my application own, and which parts should I delegate to a managed AWS service?

That question led me toward Amazon Bedrock Managed Knowledge Bases.

The Alternative: Amazon Bedrock Managed Knowledge Bases

Amazon Bedrock Knowledge Bases provides a managed abstraction for building RAG applications.

Instead of my application owning every component of the retrieval pipeline, the architecture becomes:

                    Company Documents
                           │
                           ▼
                      Amazon S3
                           │
                           ▼
               ┌───────────────────────┐
               │ Amazon Bedrock        │
               │ Managed Knowledge     │
               │ Base                  │
               │                       │
               │ Parsing               │
               │ Chunking              │
               │ Embeddings            │
               │ Indexing              │
               │ Retrieval             │
               └───────────┬───────────┘
                           │
                    Relevant Context
                           │
                           ▼
                  Application Layer
                           │
                           ▼
                  Foundation Model
                           │
                           ▼
                       Response

That creates a significantly different responsibility boundary.

My application remains responsible for the business logic, orchestration, model invocation, and user experience.

The Knowledge Base handles much of the document ingestion and retrieval pipeline.

What Exactly Does the Knowledge Base Manage?

It is important not to think of a managed Knowledge Base as simply "a vector database."

That misses most of the abstraction it provides.

During ingestion, Amazon Bedrock processes the source content, splits it into chunks, generates embeddings, and indexes the resulting vectors for retrieval while maintaining their relationship to the source documents.

Conceptually:

Source Document
      │
      ▼
   Parsing
      │
      ▼
   Chunking
      │
      ▼
  Embeddings
      │
      ▼
 Vector Index
      │
      ▼
   Retrieval

This means the Knowledge Base owns a substantial portion of the RAG data pipeline that would otherwise have to be implemented and operated by the application.

Why Amazon S3?

I wanted the original company documents to remain in an object-storage layer rather than making the vector index the primary source of truth.

Amazon S3 became that source layer.

The document structure was:

ai-creative-content/

├── brand-guidelines/
├── past-scripts/
├── captions/
└── proposals/

This gives the architecture a clear separation:

S3
│
└── Original company documents

Knowledge Base
│
└── Searchable representation of those documents

The S3 data source can be configured with inclusion prefixes, allowing the Knowledge Base to process specific paths within the bucket. It also supports synchronization when documents are added, modified, or deleted.

That separation became particularly useful because the original documents remain easy to manage independently of the retrieval layer.

Creating the S3 Data Source

At the AWS API level, the Knowledge Base data source can be configured with an S3 bucket and optional inclusion prefixes.

For example:

{
  "s3Configuration": {
    "bucketArn": "arn:aws:s3:::ai-creative-content",
    "inclusionPrefixes": [
      "brand-guidelines/",
      "past-scripts/",
      "captions/",
      "proposals/"
    ]
  },
  "type": "S3"
}

The important part is that the Knowledge Base is not simply scanning an arbitrary bucket.

The data source configuration tells Bedrock which S3 location contains the documents that belong to the Knowledge Base.

The S3 bucket and Knowledge Base also need to satisfy the regional requirements, and the Knowledge Base service role needs permission to access the configured data source.

Ingestion: Turning Documents into Searchable Knowledge

Uploading a document to S3 is only the beginning.

The document must be ingested into the Knowledge Base before it can participate in retrieval.

The high-level flow is:

PDF
 │
 ▼
Amazon S3
 │
 ▼
Knowledge Base Data Source
 │
 ▼
Ingestion Job
 │
 ├── Parse
 ├── Chunk
 ├── Generate Embeddings
 └── Index
 │
 ▼
Queryable Knowledge Base

Ingestion transforms the source content into representations that can be searched semantically.

This distinction is important:

S3 upload
   ≠
Knowledge Base ingestion

A document existing in S3 does not automatically mean it is available for retrieval.

Starting an Ingestion Job

Once the S3 data source is configured, an ingestion job can be started through the AWS Console or CLI.

For example:

aws bedrock-agent start-ingestion-job \
  --knowledge-base-id <knowledge-base-id> \
  --data-source-id <data-source-id> \
  --region us-east-1

The command starts an ingestion job for the specified Knowledge Base and data source.

The response includes an ingestion job ID, which can then be used to monitor the job:

aws bedrock-agent get-ingestion-job \
  --knowledge-base-id <knowledge-base-id> \
  --data-source-id <data-source-id> \
  --ingestion-job-id <ingestion-job-id> \
  --region us-east-1

The operational flow is therefore:

StartIngestionJob
       │
       ▼
Ingestion Job
       │
       ▼
Monitor Status
       │
       ▼
   COMPLETE
       │
       ▼
Knowledge Base Ready
for Retrieval

This became an important operational distinction during the project.

When troubleshooting RAG, I could no longer assume that:

"The file exists in S3"

meant:

"The Knowledge Base can retrieve it."

The document has to successfully pass through the ingestion pipeline first.

Incremental Synchronization

Another useful property of the S3 data source is incremental synchronization.

Suppose the Knowledge Base already contains:

Brand Guidelines
Script Bank
Caption Bank
Proposal Template

Then the caption bank is updated.

The architecture does not require me to manually rebuild the entire retrieval system.

After synchronization, the affected content can be reprocessed:

                Existing Knowledge Base
                         │
                  Document Change
                         │
                         ▼
                    Amazon S3
                         │
                         ▼
                       Sync
                         │
                         ▼
              Detect Changed Content
                         │
                         ▼
                 Re-process Content
                         │
                ┌────────┼────────┐
                ▼        ▼        ▼
             Parsing  Chunking  Embedding
                         │
                         ▼
                       Index
                         │
                         ▼
                Updated Knowledge Base

This is one of the operational advantages of using a managed data source rather than implementing a custom document synchronization pipeline.

Chunking

Chunking is one of the most important stages of the ingestion process.

A document can contain hundreds or thousands of lines. Treating the entire document as one retrieval unit makes precise retrieval difficult.

Instead, the document is divided into smaller chunks.

For example:

Brand Guidelines
       │
       ├── Chunk 1: Company overview
       ├── Chunk 2: Brand positioning
       ├── Chunk 3: Brand voice
       ├── Chunk 4: Social media guidelines
       ├── Chunk 5: Visual identity
       └── ...

Amazon Bedrock supports multiple chunking strategies, including fixed-size, hierarchical, semantic, and no-chunking configurations depending on the Knowledge Base setup.

The resulting chunks are then embedded and indexed for retrieval.

This is an important architectural detail because retrieval quality is influenced not only by the vector store, but also by how the original documents were divided before indexing.

Embeddings

After chunking, each chunk needs a numerical representation that allows semantic similarity to be calculated.

Conceptually:

Document Chunk
      │
      ▼
Embedding Model
      │
      ▼
Vector Representation
      │
      ▼
Vector Index

At query time, the user's question is also represented in a form that can be compared against the indexed content:

User Question
      │
      ▼
Query Representation
      │
      ▼
Similarity Search
      │
      ▼
Relevant Chunks

The Knowledge Base uses the embedding configuration selected during its creation to generate the vector representations used for retrieval.

This is another responsibility I did not have to implement as a separate application pipeline.

Retrieval

Once ingestion succeeds, the Knowledge Base can be queried.

Suppose a staff member asks:

"What tone should our social media captions use?"

The retrieval flow becomes:

User Question
      │
      ▼
Knowledge Base
      │
      ▼
Semantic Retrieval
      │
      ├── Brand Guidelines chunk
      ├── Caption Bank chunk
      └── Other relevant chunk
      │
      ▼
Retrieved Context

Amazon Bedrock provides the Retrieve operation for retrieving source chunks relevant to a query.

This was important to my architecture because I wanted retrieval to remain an explicit stage of the application flow rather than hiding it behind a single black-box operation.

Why Retrieval Count Matters

The number of chunks retrieved is another configuration decision.

For managed Knowledge Bases, numberOfResults controls the maximum number of source chunks returned. The actual number can be lower if fewer relevant results are available.

For example:

{
  "retrievalConfiguration": {
    "managedSearchConfiguration": {
      "numberOfResults": 5
    }
  }
}

The important word is maximum.

Setting:

numberOfResults = 5

does not mean:

Always return exactly five chunks.

It means:

Return up to five relevant chunks.

More retrieved content is not automatically better.

If a question can be answered using two highly relevant chunks, adding several loosely related chunks may introduce unnecessary context into the model prompt.

So retrieval count becomes a tuning parameter influenced by:

Document structure
Chunking strategy
Question complexity
Retrieval quality
Model context requirements

Retrieve vs. Generation

Another important architectural distinction is separating retrieval from generation.

The Knowledge Base can retrieve the relevant source material, while the application remains responsible for passing that context to the foundation model.

For my architecture:

User Question
      │
      ▼
Retrieve
      │
      ▼
Relevant Chunks
      │
      ▼
Application Orchestrator
      │
      ▼
Claude Sonnet 4.5
      │
      ▼
Generated Response

This separation gives the application control over how retrieved information is incorporated into the model request.

It also makes the system easier to debug.

Instead of treating the final answer as one opaque operation, I can inspect two separate stages:

Retrieval
    ↓
Did I retrieve the right information?

Generation
    ↓
Did the model produce the right answer from that information?

Those are fundamentally different failure modes.

Why This Separation Mattered to My Application

The application was not intended to be an autonomous agent.

It was designed as an internal creative assistant with human review.

So I wanted the architecture to remain explicit:

Staff
 │
 ▼
Application
 │
 ▼
Retrieve Company Knowledge
 │
 ▼
Construct Context
 │
 ▼
Claude
 │
 ▼
Draft Response
 │
 ▼
Human Review

This creates a clear boundary between:

Retrieval

and:

Generation

That boundary is useful both architecturally and operationally.

If an answer is incorrect, I can investigate whether:

the wrong information was retrieved, or
the correct information was retrieved but the model generated an incorrect response.

That is much more actionable than simply knowing that "the AI got it wrong."

Source Attribution

Retrieval should also remain observable.

A useful RAG system should allow the application to understand where retrieved information came from.

The Retrieve response includes the retrieved source content and source-location information.

Conceptually:

Generated Response
       │
       ├── Source: Brand Guidelines
       ├── Source: Caption Bank
       └── Source: Script Bank

For an internal assistant, this provides an additional layer of transparency.

The employee should not have to blindly trust a generated response. The application should be able to associate the response with the company information used to produce it.

What I Gained by Choosing the Managed Approach

The biggest advantage was a clearer responsibility boundary.

My application owns:

Authentication
API
Application Logic
Prompt Construction
Model Invocation
User Interface
Human Review
Access Control
Observability

The managed Knowledge Base handles much of:

Data Source Integration
Document Ingestion
Parsing
Chunking
Embedding Generation
Vector Indexing
Retrieval

That means fewer retrieval-specific components become part of my application code and operational surface.

What I Gave Up

Choosing a managed abstraction also means giving up some low-level control.

That tradeoff is important.

Lower-level / Self-managed	Managed Knowledge Base
More direct control over vector infrastructure	Higher-level AWS abstraction
More control over retrieval implementation	Bedrock-managed retrieval
More responsibility for ingestion	Managed ingestion workflow
More infrastructure to configure	Less application-owned infrastructure
More flexibility at the infrastructure layer	Less low-level control
More operational responsibility	Lower operational overhead

So I would not describe the managed Knowledge Base as universally better.

The appropriate architecture depends on the application's requirements.

If an application required highly customized vector infrastructure or retrieval behavior, a lower-level architecture could make sense.

For this project, I valued the managed ingestion and retrieval pipeline more than having complete ownership of the underlying vector infrastructure.

The Final Architecture

After working through those tradeoffs, the AI architecture became:

                       Company Documents
                              │
                              ▼
                         Amazon S3
                              │
                              ▼
                    S3 Data Source
                              │
                              ▼
                   Ingestion / Sync
                              │
                ┌─────────────┴─────────────┐
                │                           │
             Parsing                    Chunking
                │                           │
                └─────────────┬─────────────┘
                              │
                              ▼
                         Embeddings
                              │
                              ▼
                        Vector Index
                              │
                              ▼
                         Retrieval
                              │
                              ▼
                     Relevant Context
                              │
                              ▼
                  Application Orchestrator
                              │
                              ▼
                     Claude Sonnet 4.5
                              │
                              ▼
                       Draft Response
                              │
                              ▼
                        Human Review

The broader application architecture was:

                         Staff User
                             │
                             ▼
                          Cognito
                             │
                             ▼
                       API Gateway
                             │
                             ▼
                    Chat Orchestrator
                             │
                  ┌──────────┴──────────┐
                  │                     │
                  ▼                     ▼
           Bedrock Knowledge      Claude Sonnet 4.5
                 Base                    │
                  │                      │
                  └──── Retrieved ───────┘
                         Context
                             │
                             ▼
                      Draft Response
                             │
                             ▼
                       Human Review

And the knowledge pipeline was:

Company Documents
       │
       ▼
      S3
       │
       ▼
Knowledge Base Data Source
       │
       ▼
    Ingestion
       │
       ├── Parsing
       ├── Chunking
       ├── Embeddings
       └── Indexing
       │
       ▼
    Retrieval

The Architecture Decision in One Sentence

If I had to summarize the decision:

I chose Amazon Bedrock Managed Knowledge Bases because I wanted AWS to handle much of the operational complexity of the RAG ingestion and retrieval pipeline while my application focused on authentication, orchestration, generation, and the user experience.

That is a more useful way to think about managed services than simply saying:

"AWS has a service that does this for me."

The important architectural question is:

Where should responsibility live?

What I Learned From the Decision

The biggest lesson was that cloud architecture is not simply about choosing the most powerful service or building everything yourself.

It is about defining boundaries.

My initial mental model was:

S3
 ↓
Vector Database
 ↓
LLM

After building the system, my mental model became:

                 SOURCE
                   │
                   ▼
                  S3
                   │
                   ▼
              INGESTION
                   │
          ┌────────┼────────┐
          ▼        ▼        ▼
       Parsing  Chunking  Embedding
                   │
                   ▼
                Index
                   │
                   ▼
               Retrieval
                   │
                   ▼
              Application
               Context
                   │
                   ▼
              Claude
                   │
                   ▼
              Response
                   │
                   ▼
             Human Review

That shift was one of the most valuable parts of the architecture decision.

I stopped thinking about RAG as simply:

"Put documents in a vector database and ask an LLM questions."

Instead, I started thinking about it as a pipeline with explicit responsibilities:

Storage
   ↓
Ingestion
   ↓
Representation
   ↓
Retrieval
   ↓
Context
   ↓
Generation
   ↓
Review

That mental model made it much easier to reason about where managed AWS infrastructure could provide value and where application-level control was still necessary.

Final Thoughts

Amazon Bedrock Managed Knowledge Bases was not simply a shortcut for me.

It was an architectural choice.

I could have owned more of the ingestion and vector-search infrastructure myself. Instead, I chose to delegate that responsibility to a managed AWS service and keep my application focused on the parts that were specific to the product.

The resulting responsibility boundaries were:

Amazon S3
    → Source documents

Bedrock Knowledge Base
    → Ingestion + retrieval

Application
    → Orchestration + context construction

Claude
    → Generation

Human
    → Final review

For this project, that division of responsibility gave me the balance I was looking for: enough control over application behavior without unnecessarily taking ownership of infrastructure that AWS could manage for me.

Building an Internal AI Assistant on AWS: A Production-Ready RAG Architecture with Amazon Bedrock

Chidubem Okoli — Mon, 21 Sep 2026 12:02:09 +0000

AI is becoming an increasingly important part of how organizations handle day to day work. But introducing AI into an organization is not just about connecting an application to an LLM and allowing people to start asking questions.

For an internal AI assistant to be useful, it needs access to the organization's own information. It also needs authentication, access control, protection around AI input and output, logging, and a clear separation between the AI system and the people responsible for reviewing its responses.

In this project, I built an internal AI assistant on AWS that allows authenticated staff to interact with an AI assistant using the organization's internal documents as its knowledge source.

The system uses:

AWS Amplify for hosting the frontend
Amazon Cognito for staff authentication
Amazon API Gateway for the API layer
AWS Lambda for application logic
Amazon Bedrock Knowledge Bases for retrieval augmented generation
Amazon Bedrock for the foundation model
Amazon Bedrock Guardrails for controlling model input and output
Amazon S3 for storing internal documents
Amazon CloudWatch for logging and monitoring
AWS IAM for permissions and access control
Terraform for infrastructure provisioning

The goal was not simply to get an AI model to generate a response.

I wanted to build the complete application around the model.

A staff member logs in, sends a request through the application, API Gateway validates the request, Lambda coordinates the AI workflow, relevant information is retrieved from the organization's documents through a managed Bedrock Knowledge Base, the model generates a response using that context, and the response is returned to the authenticated staff member.

The system was also designed around a human review process. The assistant generates drafts and responses for staff to review. It does not automatically publish content or take actions on behalf of the organization.

Key takeaways

Building this project gave me practical experience working with multiple AWS services as one system rather than learning each service in isolation.

Building and hosting a static frontend on AWS with AWS Amplify
Implementing authentication with Amazon Cognito
Protecting an API with JWT authentication
Building a serverless backend with Lambda
Connecting Lambda to Amazon Bedrock
Building a RAG workflow using Bedrock Knowledge Bases
Using S3 as a document source
Applying Bedrock Guardrails to AI requests and responses
Debugging IAM permission issues
Working with Bedrock model access and inference profiles
Monitoring Lambda execution with CloudWatch
Managing the infrastructure with Terraform
Designing an AI workflow where humans remain responsible for the final output

Introduction

There are many areas where employees repeatedly need to search through documents, look at previous work, check company guidelines, draft content, or find information that already exists somewhere inside the organization.

The problem is that having the information does not necessarily mean that it is easy to use.

Important documents can be spread across different files and folders. Previous scripts, captions, proposals, brand guidelines and other internal resources can become difficult to search through manually.

This was the problem I wanted to address with this project.

The idea was to build an internal AI assistant that could give staff a simpler way to interact with the organization's existing knowledge.

Instead of manually searching through multiple documents before starting a task, a staff member could ask the assistant a question and have the system retrieve relevant information from the organization's internal knowledge base.
I also wanted the responses to be grounded in the organization's own information rather than relying entirely on the model's general knowledge.

That led me to use a Retrieval Augmented Generation architecture with Amazon Bedrock Knowledge Bases.

At a high level, internal documents are stored in Amazon S3 and connected to a Bedrock Knowledge Base. When a staff member submits a request, the application retrieves relevant information from the knowledge base and uses that information as context for generating the response.

But building the complete system required more than the RAG component.

I also needed to solve authentication, API security, permissions, input and output controls, application logic, logging and infrastructure provisioning.

That is what made this project interesting from an engineering perspective.

I was not just connecting an application to an AI model. I was building an internal application around it.

The Use Case

The assistant was designed for internal staff who need to work with the organization's existing content and information.

The knowledge base included areas such as

Brand guidelines
Previous scripts
Captions
Client proposals

The documents were organized in Amazon S3 using separate prefixes:

brand-guidelines/
past-scripts/
captions/
proposals/

For example, a staff member could ask the assistant to create a draft based on the organization's existing style and previous work.

Instead of relying only on the model's general knowledge, the application could retrieve relevant internal content and use it as context.

This gives the system two important components.

The model provides the language generation capability.

The organization's documents provide the context.

The application brings the two together.

The Problem I Needed to Solve

Before building the system, I had to answer a few practical questions.

1. How would staff authenticate?

The assistant was intended for internal use, so I needed an authentication mechanism that would prevent unauthenticated users from accessing the application API.

I used Amazon Cognito User Pools for this.

2. How would the frontend communicate with the backend securely?

The browser needed to communicate with an API, but I did not want the frontend directly interacting with Bedrock or having broad AWS permissions.

I used Amazon API Gateway as the API layer and configured a JWT authorizer using tokens issued by Cognito.

3. How would the assistant use internal knowledge?

A foundation model would not automatically know the organization's private documents.

I needed a retrieval layer that could search the organization's content and provide relevant information to the model.

This is where Amazon Bedrock Knowledge Bases came into the architecture.

4. How would the documents be managed?

Amazon S3 became the document repository and the source for the Knowledge Base.

5. How would I control what the AI could process and return?

An internal AI assistant still needs controls around what users can submit and what the system can return.

I used Amazon Bedrock Guardrails for this.

6. How would I troubleshoot the system?

With several managed services involved, I needed visibility into what was happening during each request.

Amazon CloudWatch provided the logging and monitoring needed to troubleshoot the backend.

7. How would I manage the infrastructure?

I wanted the infrastructure to be reproducible rather than relying entirely on manual configuration through the AWS console.

I used Terraform to provision and manage the AWS resources.

Solution Architecture Overview

The final architecture connects the staff member's browser to several AWS managed services.

The main request path is:

Staff → Amplify → Cognito → API Gateway → Lambda → Guardrails → Knowledge Base → Bedrock Model → Guardrails → Response

The supporting data path is:

S3 → Bedrock Knowledge Base → Document processing and indexing

CloudWatch provides observability across the backend, while IAM controls access between the AWS services.

Here's the complete architecture.

Request Flow

The staff member opens the frontend hosted on AWS Amplify.
The staff member authenticates through Amazon Cognito.
Cognito issues the authentication tokens required by the application.
The frontend sends the authenticated request to Amazon API Gateway.
API Gateway validates the JWT before allowing the request to reach Lambda.
AWS Lambda receives the request and acts as the orchestration layer.
The request passes through the configured Bedrock Guardrails.
Lambda retrieves relevant information from the Bedrock Knowledge Base.
The retrieved information is provided as context for the model generation step.
Amazon Bedrock generates the response.
The generated response passes through the output controls.
Lambda formats the response and returns it through API Gateway.
The frontend displays the response to the authenticated staff member.

The important part of this architecture is the separation of responsibilities. The browser handles the user interface, Cognito handles authentication, API Gateway protects the API boundary, Lambda coordinates the workflow, Bedrock handles retrieval and generation, S3 stores the source documents, and CloudWatch provides visibility into the system.

Step-by-Step Implementation

1. Building the Frontend

I started with a simple frontend.

I did not need a large frontend framework for this application because the main purpose of the interface was to provide staff with a simple way to authenticate, enter a prompt and view the generated response.

The frontend was built using:

HTML
CSS
JavaScript

The application contained the basic interface required for the assistant.

The important part here was that the frontend was intentionally kept simple.

Most of the complexity of the application lives in the backend and AWS services.

The browser is responsible for providing the user interface and communicating with the API.

It should not be responsible for directly accessing the organization's S3 documents, invoking Bedrock models or managing broad AWS permissions.

Hosting the frontend

I hosted the static frontend using AWS Amplify.

The deployment model was straightforward.

The frontend files were deployed to Amplify and served to staff through the application's web interface.

This also gave me a clean separation between the presentation layer and the backend.

The browser communicates with the API.

The API communicates with the backend services.

The backend communicates with Bedrock and the organization's internal knowledge.

Screenshot: Frontend of the internal ai assistant deployed with amplify

2. Adding Staff Authentication with Amazon Cognito

The next problem was authentication.

Because this was an internal application, I needed to make sure that only authenticated staff could access the assistant.

I used Amazon Cognito User Pools for this.

The Cognito User Pool became the identity layer for the application.

I configured the application so that users could authenticate through Cognito's managed login experience.

The basic authentication flow was:

Staff member
      ↓
Amazon Cognito Managed Login
      ↓
Successful authentication
      ↓
Authentication tokens
      ↓
Frontend

The frontend then uses the authentication information when communicating with the backend API.

Why Cognito was placed before the API

I wanted authentication to happen before the request reached the application logic.

This meant the Lambda function did not need to implement the basic responsibility of determining whether a request was authenticated.

Instead, API Gateway could validate the JWT issued by Cognito.

The request path therefore became:

Browser
   ↓
Cognito authentication
   ↓
JWT
   ↓
API Gateway
   ↓
JWT validation
   ↓
Lambda

This gave me a cleaner separation of responsibilities.

Cognito handled identity.

API Gateway handled API-level authentication.

Lambda handled application logic.

Screenshot: Cognito User Pool overview

3. Creating the API with Amazon API Gateway

Once authentication was in place, I needed an API for the frontend to communicate with the backend.

I used Amazon API Gateway with an HTTP API.

The application exposed a chat endpoint for the assistant.

The important part of this configuration was the JWT authorizer.

The API Gateway route was configured to validate tokens issued by the Cognito User Pool.

That meant a request without a valid token should not reach the Lambda function.

I tested this during implementation.

When I attempted to access the API without valid authentication, the API returned:

401 Unauthorized

This was an important test because it confirmed that the JWT authorizer was enforcing authentication at the API layer.

Screenshot: API Gateway route and JWT authorizer

4. Building the Lambda Chat Orchestrator

After API Gateway validates the request, the request is passed to AWS Lambda.

I used a Python Lambda function as the chat orchestrator.

The Lambda function became the central piece connecting the application to the Bedrock services.

Instead of allowing the frontend to directly communicate with Bedrock, the Lambda function controlled the workflow.

Conceptually, the Lambda function is responsible for:

Receive request
      ↓
Validate/process input
      ↓
Apply input guardrail
      ↓
Retrieve relevant knowledge
      ↓
Generate response
      ↓
Apply output guardrail
      ↓
Return response

This was one of the most important architectural decisions in the project.

The frontend does not need to know how the Bedrock Knowledge Base works.

It does not need to know the model configuration.

It does not need direct permissions to invoke the model.

It simply sends a request to the API.

Lambda handles the orchestration.

Screenshot: Lambda configuration

5. Storing Internal Documents in Amazon S3

The assistant needed access to the organization's existing information.

I used Amazon S3 as the document repository.

I organized the documents into separate prefixes:

brand-guidelines/
past-scripts/
captions/
proposals/

This made the document source easier to organize and gave the knowledge base a structured location from which to retrieve information.

The important point here is that S3 is not the component generating the answer.

S3 stores the source documents.

The Bedrock Knowledge Base uses those documents as its data source.

That distinction becomes important when looking at the RAG workflow.

Screenshot: S3 bucket and prefixes

6. Creating the Amazon Bedrock Knowledge Base

This was the part of the architecture that allowed the assistant to work with the organization's internal knowledge.

I created a managed Amazon Bedrock Knowledge Base and connected it to the S3 document source.

The documents then go through the knowledge base ingestion process.

At a high level:

S3 documents
     ↓
Knowledge Base data source
     ↓
Ingestion
     ↓
Document processing
     ↓
Chunking
     ↓
Embeddings
     ↓
Vector representation
     ↓
Retrieval

When a staff member asks a question, the system can retrieve relevant chunks from the indexed content.

The model can then use those retrieved chunks when generating its response.

One of the problems I encountered

The first ingestion test did not work as expected.

The issue was not with the PDF itself.

The problem was the relationship between the S3 object location and the configured data source.

The knowledge base was configured to look at a particular S3 prefix, while the test document was not located where the data source expected it.

After correcting the S3 location and running ingestion again, the ingestion job completed successfully.

The result showed:

Status: COMPLETE
Scanned: 1
Indexed: 1
Failed: 0

That was a useful debugging lesson because it showed that a RAG system can fail before the model is ever involved.

If the knowledge base does not ingest the documents correctly, there is nothing useful for the model to retrieve.

Screenshot: Knowledge Base configuration

7. Adding Amazon Bedrock Guardrails

The next part of the implementation was controlling the AI interaction.

I used Amazon Bedrock Guardrails to add controls around the assistant's input and output.

The Lambda orchestration flow therefore became:

User prompt
    ↓
Input Guardrail
    ↓
Knowledge retrieval
    ↓
Model generation
    ↓
Output Guardrail
    ↓
Final response

The guardrail configuration was an important part of the project because it demonstrated that the AI model was not being treated as an unrestricted component.

Guardrail debugging

I also ran into an issue with Guardrail versioning.

I had changed the guardrail configuration and expected the active version to reflect the new configuration.

However, the existing guardrail version was immutable.

A configuration change did not automatically mutate the already-created version.

During testing, an address was still being detected even after I had removed that configuration from the desired Terraform definition.

The test returned:

GUARDRAIL_INTERVENED

and identified the address category.

This made it clear that the Lambda was still referencing the older guardrail version.

I resolved this by replacing the guardrail version through Terraform and then verifying that the Lambda was using the new version.

The Terraform operation was:

terraform apply -replace=aws_bedrock_guardrail_version.creative_assistant

This was one of the more useful lessons from the project.

With versioned AWS resources, changing the Terraform configuration does not always mean that an existing immutable version will change in place.

You need to understand which resource is actually being referenced at runtime.

Screenshot: Guardrail overview

8. Connecting the Lambda Function to the Bedrock Model

After the knowledge retrieval layer was working, I connected the Lambda orchestrator to the Bedrock foundation model.

The Lambda function needed permissions to invoke the model.

This introduced another issue during testing.

The application initially reached the knowledge retrieval stage successfully, but model generation failed because the Lambda execution role did not have the required bedrock:InvokeModel permission for the model invocation path.

This was visible in the CloudWatch logs.

The useful part of the debugging process was that the logs showed that the earlier parts of the workflow were already working.

The input guardrail had passed.

The knowledge base had returned a result.

The failure happened when the application attempted to invoke the model.

That narrowed the problem down to the model invocation and IAM configuration rather than the entire application.

I updated the IAM permissions and continued testing.

I also encountered an issue with model throughput.

The base Claude Sonnet 4.5 foundation model identifier did not support the on-demand invocation pattern I was using.

The solution was to use the appropriate US inference profile for Claude Sonnet 4.5.

The model configuration was then updated in Terraform and the Lambda environment.

This was another useful AWS lesson.

Having access to a model in Amazon Bedrock does not automatically mean that every model identifier can be invoked using every invocation method.

The model ID, inference profile and IAM permissions all need to line up with the way the application is invoking the model.

9. IAM Permissions

IAM was used throughout the architecture to control which AWS resources each component could access.

The frontend does not need permission to invoke Bedrock.

The frontend does not need permission to read the internal S3 documents.

The Lambda function is the component that needs permissions to interact with the services required for the AI workflow.

This is where the principle of least privilege becomes important.

Instead of giving the application broad AWS permissions, I created permissions around the actual operations required by the system.

The Lambda execution role needed access to the relevant Bedrock operations and supporting resources.

The Knowledge Base also needed the permissions required to access its configured data source.

This separation helped keep the trust boundaries clear.

Frontend
   ↓
API Gateway
   ↓
Lambda
   ↓
Bedrock services

The browser never receives broad AWS permissions that would allow it to directly interact with the internal infrastructure.

10. Adding CloudWatch for Observability

Once several AWS services are connected together, debugging becomes much easier when there is a clear place to inspect what happened.

I used Amazon CloudWatch for Lambda logging and monitoring.

CloudWatch became particularly useful during the problems I encountered while testing the system.

For example, one request initially returned:

500
Unable to generate the draft.

From the frontend alone, that error did not tell me much.

The CloudWatch logs provided the actual execution path.

I could see that:

Input Guardrail
       ↓
Passed

Knowledge Base
       ↓
Retrieved result

Model invocation
       ↓
Failed

That completely changed the debugging process.

Instead of guessing whether Cognito, API Gateway, Lambda, the Knowledge Base or the model was responsible, I could follow the execution path and identify the stage where the request failed.

Screenshot: CloudWatch logs

11. Managing the Infrastructure with Terraform

I used Terraform to provision and manage the AWS infrastructure for the project.

By this point, the application involved several services, including Cognito, API Gateway, Lambda, S3, Bedrock Knowledge Bases, Bedrock Guardrails, IAM and CloudWatch. Creating and configuring all of these manually through the AWS console would make the environment harder to reproduce and maintain.

I therefore defined the infrastructure as code.

The Terraform configuration was split into separate files based on the resources they managed, including:

terraform/
├── api-gateway.tf
├── cloudwatch.tf
├── cognito.tf
├── guardrail.tf
├── iam.tf
├── knowledge-base.tf
├── lambda.tf
├── s3.tf
├── variables.tf
└── outputs.tf

This also became useful during debugging.

For example, when I discovered that the Claude Sonnet 4.5 model invocation required a different inference profile and corresponding IAM configuration, I could make the changes in Terraform and use:

terraform plan

to see exactly what Terraform intended to change before applying it.

I also ran into an issue with the Bedrock Guardrail version. The configuration had changed, but the existing guardrail version was immutable, so changing the Terraform configuration alone did not update the version being used by Lambda.

I resolved this by explicitly replacing the guardrail version:

terraform apply -replace=aws_bedrock_guardrail_version.creative_assistant

This was one of the practical benefits of using Terraform in the project. Infrastructure changes, including changes required while debugging, could be tracked and reproduced rather than relying entirely on manual console changes.

Terraform was therefore not part of the runtime request path. It was the infrastructure layer used to provision and manage the AWS resources that made the application possible.

Testing the Complete Workflow

Once the individual components were configured, I tested the application as a complete system.

The final workflow was:

Staff member
      ↓
AWS Amplify frontend
      ↓
Amazon Cognito authentication
      ↓
JWT
      ↓
Amazon API Gateway
      ↓
JWT validation
      ↓
AWS Lambda
      ↓
Amazon Bedrock Guardrail
      ↓
Amazon Bedrock Knowledge Base
      ↓
Relevant internal context
      ↓
Claude Sonnet 4.5
      ↓
Output Guardrail
      ↓
Lambda response
      ↓
API Gateway
      ↓
Frontend
      ↓
Staff member

CloudWatch provided visibility into the backend execution while Terraform provided the infrastructure management layer around the application.

The important thing about the architecture is that each service has a specific responsibility.

The frontend provides the interface.

Cognito handles identity.

API Gateway protects the API boundary.

Lambda orchestrates the workflow.

S3 stores the source documents.

Bedrock Knowledge Bases handles retrieval.

Bedrock provides the model.

Guardrails provide AI safety controls.

IAM controls permissions.

CloudWatch provides observability.

Terraform manages the infrastructure.

This gave me a reproducible way to manage the environment instead of relying entirely on changes made manually through the AWS console.

What I Learned Building It

The biggest lesson from this project was that building an AI application is not simply a matter of choosing a model.

The model was only one component of the system.

Most of the engineering work was around everything surrounding it.

Authentication had to work.

The API had to reject unauthenticated requests.

The documents had to be ingested correctly.

The knowledge base had to return useful context.

The Lambda execution role needed the correct permissions.

The model invocation method had to match the selected model and inference profile.

Guardrail versions needed to be managed correctly.

And when something failed, CloudWatch needed to provide enough information to understand where the failure occurred.

That was what made the project useful to me from a cloud engineering perspective.

I was able to work with several AWS services as one system instead of treating each service as an isolated topic.

The final result was an internal AI assistant where authenticated staff can interact with an AI system grounded in the organization's own content, while keeping the actual content generation process under human review.

Final Thoughts

This project started with a relatively simple idea.

Give staff an easier way to work with information that already exists inside the organization.

The implementation ended up involving authentication, API security, serverless computing, object storage, managed RAG, foundation models, guardrails, IAM, monitoring and infrastructure as code.

That was the part I found most valuable.

The AI model is only one piece of the application.

The real engineering challenge is building the system around it in a way that is secure, observable, reproducible and useful to the people who are going to use it.

Building a Custom VPC on AWS with Terraform: Understanding the Architecture

Chidubem Okoli — Wed, 26 Aug 2026 21:03:23 +0000

A VPC (Virtual Private Cloud) is the foundation for networking in AWS. It provides an isolated virtual network where AWS resources such as EC2 instances, databases, and application servers can communicate with each other and with external services in a controlled way.

In this project, I provisioned a custom VPC using Terraform and configured public and private subnets, routing, internet connectivity, security controls, an EC2 instance and an S3 Gateway VPC Endpoint.

More importantly, this project helped me understand how these networking components fit together rather than treating them as isolated AWS resources.

The Architecture

The infrastructure consists of:

A custom VPC using 10.0.0.0/16
A public subnet using 10.0.1.0/24
A private subnet using 10.0.2.0/24
Two Availability Zones
An Internet Gateway
Separate public and private route tables
A security group allowing SSH only from my IP
An EC2 instance in the public subnet
An S3 Gateway VPC Endpoint connected to the private route table
DNS support and DNS hostnames enabled

The architecture can be represented as:

                         INTERNET
                             │
                             │
                    ┌────────▼────────┐
                    │ Internet Gateway│
                    └────────┬────────┘
                             │
              ┌──────────────┴──────────────┐
              │            VPC              │
              │         10.0.0.0/16         │
              │                             │
              │  ┌───────────────────────┐  │
              │  │    Public Subnet      │  │
              │  │     10.0.1.0/24       │  │
              │  │      eu-west-2c        │  │
              │  │                       │  │
              │  │        EC2             │  │
              │  │         │              │  │
              │  │   Security Group      │  │
              │  └───────────────────────┘  │
              │                             │
              │  ┌───────────────────────┐  │
              │  │   Private Subnet      │  │
              │  │     10.0.2.0/24       │  │
              │  │      eu-west-2b        │  │
              │  │                       │  │
              │  │   Private Route Table │  │
              │  │          │            │  │
              │  │          ▼            │  │
              │  │    S3 Gateway        │  │
              │  │      Endpoint        │  │
              │  └───────────────────────┘  │
              │                             │
              └─────────────────────────────┘

1. Creating the VPC

The VPC is the top-level network boundary for the infrastructure.

resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_support   = true
  enable_dns_hostnames = true
  tags = {
    Name = "main-vpc"
  }
}

The VPC uses the CIDR block:

10.0.0.0/16

This provides the address space from which the subnets are created.

The /16 gives the VPC a large address range, while smaller /24 networks can be carved out for individual subnets.

I also enabled DNS support and DNS hostnames so resources inside the VPC can use AWS-provided DNS functionality.

2. Dividing the VPC into Subnets

A VPC is a large network, so it is common to divide it into smaller networks called subnets.

I created two:

Public subnet:  10.0.1.0/24
Private subnet: 10.0.2.0/24

The public subnet is located in eu-west-2c, while the private subnet is located in eu-west-2b.

resource "aws_subnet" "public" {
  vpc_id                  = aws_vpc.main.id
  cidr_block              = var.public_subnet_cidr
  availability_zone       = "eu-west-2c"
  map_public_ip_on_launch = true
  tags = {
    Name = "public-subnet"
  }
}

resource "aws_subnet" "private" {
  vpc_id            = aws_vpc.main.id
  cidr_block        = var.private_subnet_cidr
  availability_zone = "eu-west-2b"
  tags = {
    Name = "private-subnet"
  }
}

A subnet belongs to one Availability Zone.

Using different Availability Zones also introduces the basic concept of fault isolation: resources can be distributed across physically separate Availability Zones instead of depending entirely on one.

What makes a subnet public?

The name public-subnet does not make a subnet public.

A subnet becomes public when its associated route table provides a route to an Internet Gateway.

This distinction is important.

3. Internet Gateway

The Internet Gateway provides connectivity between the VPC and the internet.

resource "aws_internet_gateway" "gw" {
  vpc_id = aws_vpc.main.id
  tags = {
    Name = "main-igw"
  }
}

However, simply attaching an Internet Gateway to the VPC does not make every subnet public.

The subnet must have a route that directs internet-bound traffic to the Internet Gateway.

That brings us to route tables.

4. Route Tables

A route table determines where network traffic should be sent.

For the public subnet, I created a route table with a default route:

resource "aws_route_table" "public" {
  vpc_id = aws_vpc.main.id
  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.gw.id
  }
  tags = {
    Name = "public-rt"
  }
}

The important part is:

0.0.0.0/0 → Internet Gateway

0.0.0.0/0 represents all IPv4 destinations.

Therefore, this route essentially says:

If traffic is destined for somewhere outside the VPC, send it toward the Internet Gateway.

The public subnet is then associated with this route table:

resource "aws_route_table_association" "public" {
  subnet_id      = aws_subnet.public.id
  route_table_id = aws_route_table.public.id
}

The private subnet has a separate route table:

resource "aws_route_table" "private" {
  vpc_id = aws_vpc.main.id
  tags = {
    Name = "private-rt"
  }
}

There is no direct route from this route table to the Internet Gateway.

Therefore, resources in the private subnet do not have a direct route to the public internet.

This is what makes the subnet private from a routing perspective.

5. Public vs Private Communication

One of the most useful things I learned from this project is that "private" does not mean "cannot communicate with anything."

Both subnets belong to the same VPC:

VPC: 10.0.0.0/16
Public subnet:  10.0.1.0/24
Private subnet: 10.0.2.0/24

The VPC has a local route that allows communication within the VPC.

Therefore, a resource in the private subnet can communicate with a resource in the public subnet using their private IP addresses, assuming security controls allow the traffic.

The difference is that the private subnet does not have a direct route to the public internet.

A simple way to think about the components is:

Route table: Where should traffic go?
Internet Gateway: Provides a path between the VPC and the internet.
Security Group: Is the traffic allowed?
Subnet: Which section of the VPC does the resource belong to?

6. Security Groups

I created a security group specifically for SSH access:

resource "aws_security_group" "allow_ssh" {
  name        = "allow_ssh"
  description = "Allow SSH inbound, all outbound"
  vpc_id      = aws_vpc.main.id
}

The inbound rule allows TCP traffic on port 22 only from my IP address:

resource "aws_vpc_security_group_ingress_rule" "ssh_ipv4" {
  security_group_id = aws_security_group.allow_ssh.id
  cidr_ipv4         = var.my_ip
  from_port         = 22
  ip_protocol       = "tcp"
  to_port           = 22
}

My IP is represented as a /32 CIDR, meaning a single IPv4 address.

This is preferable to opening SSH to:

0.0.0.0/0

which would allow SSH attempts from any IPv4 address.

For outbound traffic, I allowed all IPv4 traffic:

resource "aws_vpc_security_group_egress_rule" "allow_all_ipv4" {
  security_group_id = aws_security_group.allow_ssh.id
  cidr_ipv4         = "0.0.0.0/0"
  ip_protocol       = "-1"
}

Security groups are stateful, meaning return traffic for an allowed connection is automatically permitted.

7. Launching the EC2 Instance

The EC2 instance is placed inside the public subnet:

resource "aws_instance" "main" {
  ami                    = var.ami_id
  instance_type          = "t2.micro"
  subnet_id              = aws_subnet.public.id
  vpc_security_group_ids = [aws_security_group.allow_ssh.id]
  key_name               = aws_key_pair.generated_key.key_name
  tags = {
    Name = "main-instance"
  }
}

When the instance is launched, AWS creates a primary Elastic Network Interface (ENI) for it.

The ENI is essentially the virtual network adapter that connects the EC2 instance to the VPC.

It is associated with things such as:

The subnet
A private IP address
Security groups

The EC2's network interface provides its connection to the VPC and carries its private network identity.

Because the instance is in the public subnet and the subnet is configured to assign public IPv4 addresses to launched instances, the instance can also receive a public IPv4 address.

This allows me to connect to it from outside the VPC using SSH, provided the route and security group rules allow the connection.

8. S3 Gateway VPC Endpoint

The private subnet doesn't have a direct route to the internet.

But I still wanted resources in the private subnet to be able to access Amazon S3 without requiring a NAT Gateway.

For this, I created an S3 Gateway VPC Endpoint:

resource "aws_vpc_endpoint" "s3" {
  vpc_id            = aws_vpc.main.id
  service_name      = "com.amazonaws.eu-west-2.s3"
  vpc_endpoint_type = "Gateway"
  route_table_ids = [
    aws_route_table.private.id
  ]
  tags = {
    Name = "s3-gateway-endpoint"
  }
}

The endpoint is associated with the private route table.

This provides a private path from the VPC to S3 without requiring the private subnet to have general internet connectivity.

Conceptually:

Private subnet
      │
      ▼
Private route table
      │
      ▼
S3 Gateway Endpoint
      │
      ▼
Amazon S3

This is different from giving the private subnet internet access through a NAT Gateway.

The subnet remains private while still being able to reach the AWS service it needs.

9. SSH Key Management

For SSH authentication, I used Terraform's TLS provider to generate an RSA private key:

resource "tls_private_key" "ec2_key" {
  algorithm = "RSA"
  rsa_bits  = 4096
}

The corresponding public key is registered with AWS:

resource "aws_key_pair" "generated_key" {
  key_name   = "registry-vpc-key"
  public_key = tls_private_key.ec2_key.public_key_openssh
}

Terraform then writes the private key to a local file:

resource "local_file" "private_key" {
  content         = tls_private_key.ec2_key.private_key_pem
  filename        = "${path.module}/registry-vpc-key.pem"
  file_permission = "0400"
}

The 0400 permission ensures that the private key file is readable only by the file owner.

10. Following an SSH Connection Through the Architecture

Putting everything together, an SSH connection from my computer to the EC2 looks roughly like this:

My Computer
     │
     │ TCP 22
     ▼
  Internet
     │
     ▼
Internet Gateway
     │
     ▼
Public Subnet
     │
     ▼
EC2 Network Interface
     │
     ▼
Security Group
     │
     │ Source IP allowed?
     │ TCP 22 allowed?
     ▼
    EC2

Several components have different responsibilities in this flow.

The route table provides the path.

The Internet Gateway provides connectivity between the VPC and the internet.

The network interface connects the EC2 to the VPC.

The security group determines whether the incoming connection is permitted.

Understanding these responsibilities makes the architecture much easier to reason about.

11. What I Built

The final infrastructure can be summarized as:

AWS Region: eu-west-2
│
└── VPC: 10.0.0.0/16
    │
    ├── Availability Zone: eu-west-2c
    │   └── Public Subnet: 10.0.1.0/24
    │       ├── Public Route Table
    │       │   └── 0.0.0.0/0 → Internet Gateway
    │       │
    │       └── EC2
    │           └── SSH allowed from my IP
    │
    └── Availability Zone: eu-west-2b
        └── Private Subnet: 10.0.2.0/24
            ├── Private Route Table
            │
            └── S3 Gateway VPC Endpoint

The project demonstrates the fundamental building blocks of AWS networking:

VPC → Subnets → Route Tables → Internet Gateway → Security Groups → Network Interfaces → EC2 → VPC Endpoints

The most important lesson for me was understanding that these components are not independent pieces of configuration. They work together to determine where resources live, where their traffic can go, and which traffic is allowed.

This foundation makes it much easier to understand more advanced AWS architectures such as load-balanced applications, private application tiers, NAT Gateways, RDS deployments, ECS, and multi-AZ infrastructure.

Deploying a React App to AWS S3 + CloudFront

Chidubem Okoli — Thu, 13 Aug 2026 23:38:59 +0000

What I built

CountryRank is a React (Vite) app for exploring and comparing countries. I deployed it to AWS using a production-grade static hosting setup: a private S3 bucket serving the build output, sitting behind CloudFront for HTTPS, caching, and correct handling of client-side routing.

Stack

React + Vite: the app itself, built to static assets with npm run build
AWS S3: private bucket storing the build output, no public access
AWS CloudFront: CDN in front of S3, HTTPS, custom error handling for SPA routing
AWS IAM (bucket policy): scoped access control via a service principal and condition
Origin Access Control (OAC): the mechanism that lets CloudFront read from the private bucket

Architecture

I built this project in two deliberate stages. I set up plain S3 static hosting first to understand the baseline, then added CloudFront and OAC after seeing the limitations of the S3-only setup.

Step 1: S3 bucket setup

Create the bucket. The name has to be globally unique, lowercase and hyphens only. Dots break SSL matching later if CloudFront gets added.
Turn off Block Public Access for this initial public-hosting stage. AWS made me type a confirmation phrase here rather than just unchecking a box, a useful signal that this is a consequential decision and not a routine toggle.
Enable static website hosting on the bucket:
- Index document: index.html
- Error document: index.html
Attach a bucket policy granting public read access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::dubem-country-rank-app/*"
    }
  ]
}

Two details worth internalizing here. Resource needs /* because s3:GetObject acts on individual objects, not the bucket itself; the bucket ARN without /* refers to the container (its configuration, its listing) rather than what's inside it. And S3 validates the bucket name in the policy against the actual bucket it's attached to, so a typo gets rejected immediately on save.

Upload the build. This is where S3's flat structure matters:

# Wrong: nests everything under a dist/ prefix, so index.html isn't found at root
aws s3 sync dist s3://dubem-country-rank-app/

# Right: the trailing slash means "copy the contents of dist", not "dist as a unit"
aws s3 sync dist/ s3://dubem-country-rank-app/

S3 has no real folders. Everything is a flat list of objects with string keys, and the console just visually groups keys that share a prefix. sync (as opposed to cp --recursive) only uploads what's changed, which matters once I'm redeploying repeatedly.

At this point the site was live on the S3 website endpoint. No server was running anywhere, just object storage answering HTTP requests. But it had real gaps: no HTTPS, no CDN, no custom domain and broken client-side routing. A path like /countries/nigeria isn't a real object in the bucket, so direct navigation or a refresh returns a 404 unless the error document papers over it. Even then, the response still carries a 404 or 403 status code, which is bad for SEO and monitoring. That's what CloudFront fixes.

Step 2: CloudFront setup

Putting CloudFront in front isn't just adding a CDN. It's a structural shift in the trust model. Three things change together:

The bucket goes back to fully private.
CloudFront gets a dedicated identity via OAC to read from it.
The bucket policy's principal changes from "*" to a scoped AWS service principal.

Creating the distribution through the guided console flow looked like this:

Distribution type: Single website or app
Origin: selected via Browse S3, which resolves to the bucket's REST/object endpoint (bucket-name.s3.region.amazonaws.com) rather than the website endpoint
No custom Route 53 domain for now; CloudFront gives a free *.cloudfront.net domain by default
WAF's managed protections left on default (free tier, no cost) rather than customized

Why the REST endpoint and not the website endpoint? OAC works by having CloudFront sign its requests to S3, and only the REST API understands signed requests. The website-hosting endpoint is public-only by design and can't validate a signature. Since the bucket is going private anyway, the website endpoint becomes irrelevant at this stage regardless.

One consequence worth flagging: the REST endpoint has no concept of index or error documents. Everything configured in Step 1's hosting settings doesn't carry over. CloudFront needs its own equivalent settings, covered next.

Step 3: Setting up OAC

Enabling "Allow private S3 bucket access to CloudFront" during distribution creation is the actual OAC toggle. It does two things: it creates an Origin Access Control resource, and it auto-generates a bucket policy update scoped to that resource.

The generated policy looked like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCloudFrontServicePrincipal",
      "Effect": "Allow",
      "Principal": { "Service": "cloudfront.amazonaws.com" },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::dubem-country-rank-app/*",
      "Condition": {
        "ArnLike": {
          "AWS:SourceArn": "arn:aws:cloudfront::942004241182:distribution/E2XUCTY83EAT31"
        }
      }
    }
  ]
}

The Condition block matters more than it looks. Service: cloudfront.amazonaws.com alone would let any CloudFront distribution in any AWS account read the bucket. Scoping it to a specific SourceArn restricts it to this one distribution. Without that, I would just be trading one public-access problem for a slightly narrower one.

Important: enabling OAC updates the bucket policy, but it doesn't touch Block Public Access or remove prior policy statements automatically. That's what bit me next.

Errors I hit and how I fixed them

1. AccessDenied on the CloudFront root URL

After the distribution deployed, hitting the CloudFront URL returned:

<Error>
<Code>AccessDenied</Code>
<Message>Access Denied</Message>
</Error>

I reasoned through it like this: when requesting /, what object key was CloudFront actually asking S3 for? Nothing in the setup so far told CloudFront that / should resolve to index.html. That's a distribution-level setting called Default Root Object, and it isn't inherited from anything configured back in Step 1.

Fix: in the distribution, go to General, click Edit and set Default Root Object to index.html.

2. Client-side routes still broken after that

Fixing the root didn't fix direct navigation to /countries/nigeria. Same underlying problem as the S3-only stage, still unresolved, because Default Root Object only handles the exact-root case.

Fix: Custom Error Responses on the distribution:

HTTP error code	Response page path	HTTP response code
403	`/index.html`	200
404	`/index.html`	200

Both codes are needed because a private bucket accessed via OAC tends to return 403 for a missing key rather than a clean 404. It doesn't distinguish "doesn't exist" from "not allowed to see it," it just denies. This is the fix plain S3 hosting couldn't offer: CloudFront can rewrite the status code itself, not just swap in different content, so a deep-linked SPA route now returns a legitimate 200 while React Router takes over client-side.

3. Old public bucket policy left stacked on top of the new one

After everything was working, I went back and checked the bucket policy directly instead of assuming the wizard had cleaned up after itself. I found the original Principal: "*" statement from Step 1 still sitting there, alongside the new CloudFront-scoped one. Block Public Access was also still off.

That meant the bucket was reachable two ways: through CloudFront (secured, cached, HTTPS) and directly via the old public endpoint (none of that), quietly defeating the point of the whole migration.

Fix:

Removed the old Principal: "*" statement, keeping only the CloudFront-scoped one.
Re-enabled Block Public Access.
Verified by testing both URLs: the CloudFront URL still worked, and the direct S3 endpoint failed. That's the actual proof the bucket is only reachable through the intended path.

What I learned

S3 access control is layered: Block Public Access is the master override, the bucket policy is the grant, and the resource ARN scope decides bucket versus object. All three have to align, and missing any one breaks things in a specific, diagnosable way.
S3 "folders" are prefixes, not real directories. This affects upload commands directly, not just how the console displays things.
Website-hosting endpoints and REST endpoints are genuinely different features with different capabilities. OAC only works with the REST one.
CloudFront doesn't inherit S3's static-hosting settings. Default Root Object and Custom Error Responses have to be configured independently, and skipping them produces specific, traceable errors rather than vague failures.
Auto-generated policies from console wizards can leave old, conflicting statements behind. It's worth checking the actual policy JSON manually rather than assuming the tool fully cleaned up after itself.
Debugging AccessDenied is faster when reasoning through which layer is missing (policy, public access block, or routing config) rather than guessing and re-toggling settings at random.

Set Up SSH Keys on Windows: A Step-by-Step Guide

Chidubem Okoli — Tue, 02 Sep 2025 08:08:57 +0000

Secure Shell (SSH) is a security protocol that creates a highly secure connection between your computer and GitHub. It uses a pair of cryptographic keys—a public key you share and a private key you keep safe—to verify your identity.

The main benefit of using SSH keys is convenience and security. Once set up, you can connect to GitHub to push and pull code without having to enter your username and personal access token every time.

Here's a step-by-step guide on how to set up your SSH keys in a Windows environment.

Step 1: Check for Existing SSH Keys
First, let's see if you already have an SSH key pair. It's good practice to avoid creating new ones if you don't have to.

a) Open PowerShell (press the Windows key, type PowerShell, and press Enter).

b) The default directory is /.ssh. Run the following command to list files in the .ssh directory, which is where keys are typically stored:

ls -a ~/.ssh

c) Look for a pair of files named something like id_rsa and id_rsa.pub, or id_ed25519 and id_ed25519.pub. If you see a .pub file, you already have a key and can skip to Step 3.

Alternatively, you can get the key by typing into the powershell terminal

cat id_ed25519.pub

Step 2: Generate a New SSH Key Pair

If you don't have an existing key, you'll need to create one. We'll generate a modern and secure Ed25519 key.

a) In your PowerShell terminal, run the following command. Make sure to replace "your_email@example.com" with the email address associated with your GitHub account.

ssh-keygen -t ed25519 -C "your_email@example.com"

b) The command will prompt you to choose a location to save the key. The default location (~/.ssh/id_ed25519) is perfect, so just press Enter.

c) Next, you'll be asked to enter a passphrase. 🔐

A passphrase adds an extra layer of security; if someone gains access to your computer, they still can't use your key without knowing the passphrase.
It's highly recommended to use one, but you can leave it blank by pressing Enter twice.

> Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

You've now created two files in your ~/.ssh directory: id_ed25519 (your private key) and id_ed25519.pub (your public key). Never share your private key!

Step 3: Add Your SSH Key to the ssh-agent
The ssh-agent is a background program that securely stores your private key and manages its passphrase so you don't have to re-enter it constantly.

a) First, ensure the ssh-agent service is running. This command will start it if it isn't active.

Start-SshAgent

b) Now, add your private SSH key to the agent.

ssh-add ~/.ssh/id_ed25519

c) If you created a passphrase in the previous step, you will be prompted to enter it now.

Step 4: Add Your Public SSH Key to GitHub
Now you need to tell GitHub about your public key so it can grant you access.
a) Now you need to copy your public SSH key. To do this, we’re going to use a command called cat to read the file to the console.

cat ~/.ssh/id_ed25519.pub

b) Open your browser and navigate to GitHub.

Click your profile picture in the top-right corner, then click Settings.
In the left sidebar, click SSH and GPG keys.

c) Click the New SSH key button.

d) In the Title field, give your key a descriptive name, like "My Windows Laptop" or "Work PC".

e) Click inside the Key field and paste your key by pressing Ctrl + V.

f) Finally, click Add SSH key. You may be asked to enter your GitHub password to confirm.

Step 5: Test Your SSH Connection
Let's make sure everything is working correctly.

a) Back in your PowerShell terminal, run this command:

ssh -T git@github.com

b) You may see a warning about the authenticity of the host. This is normal for the first connection.

The authenticity of host 'github.com (IP ADDRESS)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Type yes and press Enter.

c) If everything is set up correctly, you'll see a welcome message with your username! 🎉

Hi your-username! You've successfully authenticated, but GitHub does not provide shell access.

You're all set! You can now clone, pull, and push to your GitHub repositories using SSH without needing to enter your credentials every time.

How I Fixed Firebase’s “Unauthorized Domain” Error While Building Resumpire

Chidubem Okoli — Wed, 09 Jul 2025 14:52:58 +0000

The Problem:

I was deep into building resumpire.vercel.app (a resume builder app) when I hit a wall. Firebase kept rejecting my authentication requests with an “Unauthorized Domain” error.

At first, I was running through all the usual suspects:

Maybe I broke something in my codebase?
Could there be a dependency version conflict?
Is there a typo in my config?

After scouring my codebase trying to find the bug, I finally spotted the issue.
Turns out, the issue was much simpler.

The Culprit: Firebase’s Authorized Domain List
Firebase Authentication only allows requests from domains you explicitly authorize. That means:

If you’re testing locally, you must add http://localhost (or your custom dev URL) to Firebase’s Authorized Domains list.

If you’re deploying, your live domain (e.g., resumpire.vercel.app) needs to be added too.

My deployed domain resumpire.vercel.app wasn't in the Firebase Authorized Domains list. I'd only added localhost during development.

How I Fixed It

Opened Firebase Console → Authentication → Settings
Scrolled to “Authorized Domains”
Added my production domain (resumpire.vercel.app)
Reloaded the app → Auth worked instantly

Lesson learned: Always check the docs (and the obvious settings) first.

Why This Matters
This wasn’t just about fixing an error—it reinforced a bigger lesson:

Small oversights cause big blockers.
Reading docs > guessing.
Every error is an avenue to learn and grow which makes you a better dev.

How I Built an AI-Powered Text Processor Using Chrome AI API.

Chidubem Okoli — Thu, 27 Mar 2025 08:40:36 +0000

Introduction

When I first discovered the Chrome AI API, I recognized its potential immediately. The ability to integrate AI-powered text processing directly into a web app—without requiring a backend—opens up new possibilities for seamless user experiences. Using React and TailwindCSS, I built a practical AI Text Processor capable of summarizing, translating, and detecting languages entirely in the browser.

In this guide, I’ll walk you through:
✔ Why the Chrome AI API is a game-changer
✔ Step-by-step setup (including troubleshooting tips)
✔ How I built the UI with React & TailwindCSS
✔ Lessons learned and where to go next

Setup & Prerequisites

Before diving in, you’ll need:

1) Comply with Google’s AI Policies

Ensure your use case follows Google’s Generative AI Prohibited Use Policy.

2) Install Chrome Canary

Download Chrome Canary (v129.0.6639.0 or newer). Why Canary? The API is experimental and only available here for now.

3) Check Storage Requirements

Minimum 22GB free storage. If storage drops below 10GB, Chrome automatically deletes the model.

4) Enable the Summarization API

Open chrome://flags/#summarization-api-for-gemini-nano
Select Enabled
Relaunch Chrome

5) Force-Download the AI Model

Open DevTools (F12) and run:

await ai.summarizer.create(); // Triggers model download await ai.summarizer.capabilities(); // Check status
Repeat the second command until it returns "readily" (~3-5 mins).

Stuck? If you see:

"The model was available but there was no execution config available for the feature."

Wait 24 hours and retry (Google rolls out access gradually).

Troubleshooting Tip: For full documentation, check Chrome’s AI API Guide here.

Why the Chrome AI API?

This API brings serverless AI to the browser with:
✅ No backend needed – Runs entirely client-side.
✅ Blazing fast – Responses in milliseconds.
✅ Privacy-focused – No data sent to third-party servers.
✅ Easy integration – Just call ai. methods like translate() or summarize().

Project Features

The AI Text Processor includes:

Text Input - A responsive text area for content entry
Language Detection - Automatic identification of input text language
Text Summarization - Concise distillation of key information
Multilingual Translation - Conversion between supported languages
Accessible Interface - Screen reader compatible with keyboard navigation
Error Handling - Graceful failure modes and user feedback

Tech Stack

React – UI components & state management.
TailwindCSS – Rapid styling.
Chrome AI API – ai.summarizer, ai.translator, ai.detector.

Building the App

1) Initialize the Project

npm create vite@latest ai-text-processor --template react cd ai-text-processor npm install

2) Add TailwindCSS

npm install -D tailwindcss postcss autoprefixer npx tailwindcss init -p

Configure tailwind.config.js:

export default { content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"], theme: { extend: {} }, plugins: [], };

Add to index.css:

@tailwind base; @tailwind components; @tailwind utilities;

3) Create the UI
A simple layout with:

A textarea for input.

Buttons for actions (Summarize/Translate/Detect).

A results panel (conditional rendering with error handling).

4) Integrate the Chrome AI API

const handleSummarize = async () => { try { const summary = await ai.summarizer.summarize(text); setResult(summary); } catch (error) { setResult("Error: " + error.message); } };

Future Improvements

More languages – Expand translation support.

Offline mode – Cache results for poor connectivity.

Custom prompts – Let users tweak summarization style.

Conclusion

The Chrome AI API opens up exciting possibilities for browser-based AI apps. While still experimental, it’s a glimpse into a future where frontend devs can leverage AI without backend complexity.

Try the demo & code

GitHub Repo Link here
Live Link here
Note: This implementation is currently available only for desktop platforms

Recreating the Interswitch Homepage with React and TailwindCSS.

Chidubem Okoli — Tue, 14 Jan 2025 13:24:30 +0000

Introduction

Recreating a modern, visually appealing landing page is always an exciting challenge. This week, I focused on building a replica of the Interswitch homepage using React and TailwindCSS. This article provides a technical walkthrough of the process, from project setup to implementing reusable components and styling. Here's how I approached it:

Project Setup with Vite

Vite has become my go-to tool for React projects due to its blazing-fast build times and simplicity. The setup process involved:

npm create vite@latest interswitch-clone --template react
cd interswitch-clone
npm install

With the development server running, I was ready to start coding.

Structuring Components

Breaking the homepage into reusable components was essential for maintainability and scalability. Below are a few key components I implemented.

NavBar Component

import { useState } from "react";
import { FaBars, FaTimes } from "react-icons/fa";
import { FiChevronDown } from "react-icons/fi";

const Navbar = () => {
  const [isOpen, setIsOpen] = useState(false);
  const [dropdownOpen, setDropdownOpen] = useState(false);

  const navLinks = [
    { title: "About Us", hasDropdown: true },
    { title: "What We Do", hasDropdown: true },
    { title: "Financial Inclusion", hasDropdown: false },
    { title: "Corporate Responsibility", hasDropdown: false },
    { title: "News & Insights", hasDropdown: false },
  ];

export default Navbar;

Stats Component

const Stats = () => {
  return (
    <div className="bg-blue-50 py-12">
      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
        <div className="flex flex-col gap-8">
          <div className="flex flex-col md:flex-row items-start gap-8">
            <h2 className="text-3xl md:text-4xl font-semibold text-gray-900 flex-1">
              Pushing the boundaries of innovation to deliver payment solutions that enable commerce across Africa
            </h2>
            <div className="flex-1 flex flex-col gap-4">
              <p className="text-xl text-gray-700">
                Bespoke payment solutions for your modern lifestyle, business collections, disbursements, and payment processing.
              </p>
              <button className="bg-blue-950 text-white px-6 py-3 rounded-md hover:bg-blue-900 transition w-fit">
                Learn More
              </button>
            </div>
          </div>
export default Stats;

Styling with TailwindCSS

TailwindCSS made styling the components seamless. By leveraging utility classes, I could focus on functionality without writing custom CSS. For example, the hero section below uses Tailwind’s gradient and typography utilities to create an eye-catching design.

const Hero = () => {
  return (
    <div className="text-blue-950 pt-6 relative">
      <div className="max-w-6xl mx-auto px-4 sm:px-6 lg:px-8">
        <div className="grid md:grid-cols-2 gap-12 items-center">
          <div>
            <h1 className="text-2xl md:text-7xl mb-6 mt-16 font- text-blue-950">
              The Gateway To Africa&apos;s Payment Ecosystem
            </h1>
            <p className="text-xl md:text-xl mb-8 text-black-200">
              We create and sustain a payment ecosystem that helps 
  commmerce evolve, businesses grow and individuals thrive.
            </p>
          </div>
       </div>
     </div>
  </div>


export default Hero;

Key Takeaways

Componentization: Breaking the UI into reusable components ensured better maintainability.
TailwindCSS: The utility-first approach made styling intuitive and efficient.
Vite: Its fast build times improved the development experience.

Conclusion

Recreating the Interswitch homepage was a rewarding experience that solidified my understanding of React and TailwindCSS. By leveraging modern tools and best practices, I built a scalable and visually appealing landing page. If you’re working on a similar project or have questions, let’s connect in the comments!

Elevate Your JavaScript Journey: Tackling Projects and Unlocking Features 🚀

Chidubem Okoli — Thu, 05 Dec 2024 17:04:36 +0000

JavaScript is an ever-evolving journey where each project adds a new layer to your skills. Whether you're building a ticketing system or adding functionality to a to-do list, there's always something new to learn! Let me walk you through my recent experiments, lessons, and insights.

Building a Ticketing System 🎟️

When working on a ticket system, I wanted to level it up by allowing users to input any number of tickets instead of relying on predefined buttons. The goal was simple: improve flexibility while keeping the system intuitive.

Here’s what I learned:

DOM Manipulation Is Key: Capturing input values dynamically and using them effectively in your JavaScript logic is vital.

Validations Matter: When you let users enter values, ensure you're checking for edge cases like negative numbers or empty inputs.

Iterate & Improve: Building on the foundational ticket counter I developed earlier, I realized how important it is to refactor code for scalability.
If you're considering a project like this, start small. Add basic functionality, then challenge yourself to build on top of it.

Adding Delete Functionality to a To-Do List ✔️❌

To-do lists are a staple project for beginners—and for good reason! They offer a practical way to learn about adding and removing elements from the DOM. Recently, I wanted to add a delete button to each item dynamically.

My Approach:

Generate Buttons on Item Creation: When the user adds a new task, a delete button is created alongside it.

Add Event Listeners Dynamically: I attached an event listener to each button to handle the deletion logic.

Parent-Child DOM Interaction: Using parentElement, I ensured clicking the delete button would remove its corresponding list item.
Here’s a snippet of the core idea:

function addTask(taskText) {

  const li = document.createElement("li");
  li.textContent = taskText;

  const deleteBtn = document.createElement("button");
  deleteBtn.textContent = "Delete";


  deleteBtn.addEventListener("click", () => {
    li.remove();
  });

  li.appendChild(deleteBtn);
  document.querySelector("#task-list").appendChild(li);
}

With this approach, I learned how important it is to structure your DOM interactions cleanly and avoid cluttered logic.

Lessons Learned 🧠

1.Experimentation Drives Learning

Projects like these reinforce that theory is nothing without practice. By experimenting with features, I gained a deeper understanding of DOM manipulation, event listeners, and JavaScript logic.

2.Simple Features, Big Impact

The smallest changes—like a delete button—can significantly enhance your project's user experience. Don't underestimate the value of small wins!

3.Learn in Layers

Building on previous projects is the best way to reinforce your skills. I started with a basic ticket counter, then expanded it. Similarly, I took my to-do list from "add-only" to "add-and-delete."

What's Next?🔮

JavaScript is all about iteration. I’m excited to explore more advanced concepts like input validations, animations, and even local storage to persist data between sessions.

If you're on a similar journey, start small and stay consistent. Every project you complete is another step forward.

Let me know in the comments—what’s your favorite beginner-friendly JavaScript project?

Happy coding! 🚀

Installing And Running NPM Packages Using The Terminal

Chidubem Okoli — Mon, 04 Nov 2024 08:57:52 +0000

When working on a JavaScript project, chances are you'll need to install and use npm (Node Package Manager) packages.

npm is essential for managing libraries and tools that enhance your development process. If you're new to this, here's a step-by-step guide to installing and running npm packages using the terminal.

Prerequisites
Install Node.js: Ensure that the recent version of Node.js is installed on your machine, as npm comes bundled with it. You can check if it's installed by running:

node -v

and

npm -v

If you don't have it installed, download it from https://nodejs.org/https://nodejs.org/ and follow the installation instructions.

After confirming it is successfully installed, create a folder for your project or navigate to an existing one.

Initialize The Project

To start using npm, you need a package.json file, which tracks the project's dependencies and scripts. You can create one by running:

npm init

You’ll be prompted with some basic questions (like project name, version, description, etc.). You can either answer each or press Enter to accept the defaults.
Alternatively, you can use npm init -y to create a default package.json file without prompts.

Installing npm Packages

With npm, you can install packages either globally or locally to your project.

Local Installation: Installs the package in the project directory and adds it to your package.json.

npm install package-name
This installs the package locally. You'll find it under the node_modules folder, and it will be listed in your package.json file.

Global Installation: Installs the package globally on your system, making it available from any directory.

npm install -g package-name

This installs the package globally, allowing you to run the package commands directly in any project without needing to install it locally.

Using npm Scripts to Run Commands

Scripts defined in package.json can simplify common tasks like running tests or starting the server. In your package.json, there’s a "scripts" section where you can define custom commands.

Example:

"scripts": { "start": "node index.js", "test": "echo \"Error: no test specified\" && exit 1" }
In this example:

"start" will run "node index.js".
You can replace "test" or "start" with other custom scripts.

To run a script, use:

npm run script-name

Running Installed Packages from the Terminal

If you installed a package globally, you can use it directly in the terminal.
For locally installed packages, use npx, which comes bundled with npm:
npx package-name
Example:

npx create-react-app my-app
This command runs the create-react-app package without needing to install it globally.

Updating and Removing Packages

To update a package, use:
npm update package-name
To remove a package, use:

npm uninstall package-name
This command will remove the package from the node_modules folder and from package.json.

Conclusion
By understanding these basic npm commands, you can confidently install, run, and manage packages in any Node.js project.