🏠 Documentation Hub 📝 Engineering Blog 💻 GitHub Repository

AI Systems Design From Scratch

(Star⭐ our Repo)

A comprehensive, zero-dependency implementation of artificial intelligence components and enterprise systems design patterns, built completely from first principles.

Also kept simple and lightweight.

This codebase operates as both a Lean MVP Builder and a Local Infrastructure Foundation. Its value lies in the fact that it eliminates the “Framework Overhead” (dependencies, configuration hell) while maintaining “Architecture Rigor.”

The “Sandboxed Enterprise”: this is essentially a private cloud on a laptop. For companies building sensitive, offline-first, or air-gapped systems (e.g., defense, edge computing, high-frequency finance), this approach is the gold standard for security and isolation.

System design foundation.

Edge-computing.

Secure by design.

Primitive principles.

Transparent, deterministic, and auditable.

AI Native infrastructure.

Modules communication via dependency injection.

Each module is treated as an AI System now.

Dependency Injection.

Skill Router.

Amin Boulouma, Software Engineer

Repository Philosophy

Zero-Dependency Engineering >, Core Philosophy

What I cannot create, I do not understand. >, Richard Feynman

Getting started

To clone and use the repository, execute:

git clone https://github.com/aminblm/ai_systems_design_from_scratch.git
cd ai_systems_design_from_scratch

Run any core system directly from src/:

# Run the key-value cache store
python3 src/py_redis.py

# Run the task scheduler engine
python3 src/py_airflow.py

# Run the REST API backend framework
python3 src/py_REST_API.py

This repository sits at the exact intersection of deep education and production-grade implementation. The ultimate goal is to demystify the inner workings of complex enterprise software, cloud infrastructure, and machine learning ecosystems by rebuilding them atom by atom.

The Zero-Dependency Mandate

To enforce genuine first-principles learning, this repository maintains a strict zero-reliance policy on external libraries.

There is no requirements.txt or pyproject.toml containing third-party packages.
The sole prerequisite is the native Python runtime.
Higher-level systems (such as neural networks or orchestration engines) must strictly import and depend on the lower-level architectures built within this repository.

What to Expect

Bridging the Complexity Gap: Implementations balance fundamental simplicity with structural complexity, guiding you from beginner-level educational concepts to advanced systems design.
Full-Stack Systems Coverage: Code components span across CI/CD mechanics, GoF design patterns, distributed databases, network load balancers, cloud primitives, and neural architectures.
Made for Builders: Built specifically for hands-on software engineers, system architects, and AI scientists who learn best by writing raw code and breaking things.
Continuous Evolution: This is a live, highly volatile work-in-progress framework. Systems are regularly refactored to achieve higher reliability, modularity, and throughput.

Requirements

Runtime: Python 3.14.5 (Standard Library Only)

Technical Roadmap

Code Base Standardization

Implement a strict codebase-wide renaming convention to explicitly differentiate internal systems from upstream engines (e.g., refactoring airflow to py_airflow, kafka to py_kafka).
Write a custom abstract syntax tree (AST) linter script to block accidental external imports.
Integrate a pure-Python automated testing suite with unified coding guidelines.

Reliability & Infrastructure Stress Testing

Bind each complete system to a dedicated port and containerize via native process isolation techniques.
Chain separate atomic technologies together to spin up end-to-end enterprise architectures.
Develop an internal traffic engine to simulate heavy concurrency, network constraints, and system load.
Inject custom chaos-engineering drivers to validate fault tolerance and state recovery during runtime failure.

Community & Tooling Integration

Enable packaging and execution testing via uv and pip exclusively for localized stress tests.
Transition the project layout into an accessible prototyping framework for rapid offline infrastructure emulation.
Compose comprehensive technical tutorials, architecture breakdowns, and system walkthroughs.

Matrix of Technologies

Here is the updated, comprehensive list of all 71 distinct technologies, tools, and concepts explicitly called out in your repository roadmap.

Complete Technology Implementation Registry

1. Core Artificial Intelligence & Machine Learning

2. Compute, Virtualization & Container Infrastructure

Docker Engine (Core container manager daemon using process namespace isolation primitives)
Docker Client (Command-line interface client to interact with your native Docker Engine)
Kubernetes (Container orchestration node management, pod allocation, and state loops)
AKS (Azure Kubernetes Service cloud wrapper orchestration)
EC2 (Elastic Compute Cloud virtual instance simulator with CPU allocation limits)
Lambda (Serverless ephemeral function runner with event triggers)
Operating system (Low-level task handling, file locks, and process scheduling)
GPU (Emulated graphic processing unit thread allocation matrices)

3. Core Networking, API & Web Architecture

Socket server (Low-level TCP/IP listening, socket binding, and socket multiplexing)
Socket client (Raw TCP connection handshake protocol and byte streamer)
FastAPI / Flask / RESTFUL API (Pure Python REST API routing framework with request/response body parsing)
Postman / RESTFUL API Client (Command-line REST API interface and endpoints stress-testing client)
Angular / React / Vue.js / Frontend (Component-based web client routing abstraction)
Node (Server-side JavaScript runtime event execution engine simulation)
Npm (Package manager installation validation tracker simulation)
API (Standardized contract layer validation and schema constraints)
Google Chrome (Virtual headless user-agent client agent for browsing simulation)

4. Storage, Databases & Streaming

SQL Engine (Relational storage parser, indexing structures, and relational execution operators)
Redis (In-memory key-value data structure store, caching layer, and pub/sub broker)
MongoDB (NoSQL BSON-like document engine, collection storage, and dynamic indexer)
ElasticSearch (Inverted-index document retrieval system and text query engine)
Kafka (Log-append streaming broker, distributed partition managers, and state logs)
S3 (Simple Storage Service bucket manager, object allocation, and metadata blobs)
Data lakes (Unstructured multi-format data directories and partition layouts)

5. Data Orchestration, Ingestion & Pipelines

Airflow (Directed Acyclic Graph DAG job runner, scheduling loops, and task state tracking)
Pipelines (Linear data transformers, staging maps, and stream extraction hooks)

6. DevOps, Cloud Providers & Infrastructure as Code (IaC)

7. Observability, Monitoring & Cybersecurity

Prometheus (Time-series metrics scraping engine and alert tracking arrays)
Grafana (Metrics parser, dashboard generation charts, and numerical visualization grids)
New Relic (Application Performance Monitoring telemetry tracker and hook agent)
AI + Cloud + DevOps + Cybersecurity (Unified system boundary security configuration engine)

8. Low-Level Core Runtimes & Engineering Utilities

Callables (Dynamic functional interfaces and execution hooks)
Promises (Asynchronous event loops, futures tracking, and unblocking resolution frameworks)
Design Patterns (Unified implementation architecture featuring creational, structural, and behavioral patterns)
Documentation generator (Source code AST parsing utility creating dynamic documentation pages)
Content generator (Automated Markdown and project layout asset text provider)
Emailing server (Simulated SMTP server tracking sent packets, relay connections, and standard text boxes)
Push Notification server (Web-socket broadcast notification stream connection engine)
ServiceNow (Enterprise ticketing management and tracking simulation dashboard)
VSCode (Internal project text editing workspaces mapping configuration files)

Other and Much more to come!

Engineering Principles:

SOLID (Single responsibility)
DRY (So not repeat yourself)
TDD
DDD

Fundamentals of System Design

Principles of Microservice Architecture

Monolithic vss SOA (Service-Oriented Architecture) vs. Microservices
7 Principles of Microservice Architecture
- DDD (Domain-Driven Design)
- Culture of automation
  - Infrastructure automation
    - Infrastructure as Code (IaaC)
      - Terraform
      - Ansible
      - AWS CloudFormation
      - Azure Resource Manager
      - Google Cloud Deployment Manager
    - Testing automation
      - Apache JMeter
      - Gatling
      - Jaeger
      - Cypress
      - Playwright
    - Continuous Delivery
      - Harness
      - Spinnaker
      - Jenkins
      - Github
      - Gitlab
- Encapsulation: Hiding Implementation Details
  - Application Programming Interfaces (API)
    - CRUD
  - Bounded Contexts
- Decentralization
  - Self-Service
  - Shared Governance
  - Smart Endpoints and Dumb Pipes

Challenges in Distributed Systems: Availability

Consistency, Availability, Partition Tolerance (CAP Theorem)
- CP
  - MongoDB
  - HBase
  - Redis
- AP
  - CouchDB
  - Cassandra
  - DynamoDB
  - Riak
- CA
  - RDBMS
Availability
- Redundancy
- Monitoring (Observability)
  - Network
  - Machine
  - Application
  - 4 Pillars
    - Monitoring
    - Alerting/visualization
    - Distriuted systems tracing infrastructure
    - Log aggregations / Analytics

Designing a System from Scratch

Functional Requirements
Non-Functional Requirements
Data Structure Design
- Inverted Index
- Binary-search Tree
- Trie
System Architecture
- Scalability
  - Horizontal scaling
    - Pros:
      - Provides infinite scaling (through elasticity)
      - Provides more fault tolerance (through Redundancy)
      - CHeaper (can be implemented with off-the-shelf hardware)
      - no need to rely on complex, specialized hardware
    - Cons:
      - Introduces the complexity of implementation
  - Vertical scaling
    - Pros:
      - Ease of implementation
    - Cons:
      - Limitation on the scale
      - Hardware becomes complex and expensive as the size increases
- Sharding
  - Random sharding
    - Hash algorithms
  - Alphabetic sharding
  - Consistent Hashing
- Availability
  - Redundancy
    - Pros:
      - Availability of duplicate shard
      - Alleviate pressure on one node
    - Cons:
      - Increase memory requirement of system
      - Extra complexity of implementation
        
        Shard routing
        
        synchronization of shard data
High-Level Diagram And Data Flow
- Client -> Load Balancer -> Web Servers (cahes) -> Indexer nodes -> Document Store (DFS)

Possible evolutions of this repository

Lightweight zero-dependency all-in-one infrastructure for rapid prototyping and validating systems before scale.
Sandbox prototyping and local development

Integration Architecture Checklists

Ensure all components strictly rely on ai_systems_design_from_scratch dependencies.
Prepend the py_ namespace prefix across all relevant directories during implementation (e.g., py_redis, py_kafka, py_tensorflow).

Contributing

Contributions are vital to pushing this framework toward absolute completeness. You can participate through the following avenues:

Feature Proposals: File an issue detailing an architectural component or cloud primitive you want to see built from scratch.
Code Submissions: Open a pull request containing optimization tweaks, behavioral alignment with target systems, or a new standard library implementation block.
Architecture Reviews: Audit existing components for edge-case errors, code readability problems, or violations of the zero-dependency rule.

Connect with Amin Boulouma Official