🧠 Self-Orbit — Personal Intelligence Platform

Cloud-native, event-driven microservice platform for personal intelligence.

Transforms unstructured text and audio into structured, actionable data—powered by AI inference, gRPC inter-service communication, and a horizontally scalable Kubernetes-ready architecture.

---

🏗️ System Architecture

graph TD
    classDef client fill:#0070f3,stroke:#0051a8,color:#fff
    classDef gateway fill:#6366f1,stroke:#4f46e5,color:#fff
    classDef microservice fill:#f59e0b,stroke:#d97706,color:#fff
    classDef ai fill:#8b5cf6,stroke:#7c3aed,color:#fff
    classDef database fill:#336791,stroke:#2a5278,color:#fff
    classDef devtools fill:#10b981,stroke:#059669,color:#fff,stroke-dasharray: 5 5

    subgraph ClientLayer
        FE["🖥️ Next.js 15 Frontend"]:::client
        DT["🛠️ Dev Tools (Browser Only)"]:::devtools
    end

    subgraph GatewayLayer
        GW["🔀 API Gateway (YARP)"]:::gateway
    end

    subgraph ServiceMesh
        ES["💰 Expense Service (.NET 10)"]:::microservice
        PS["📅 Productivity Service (.NET 10)"]:::microservice
    end

    subgraph AIInfra
        AI["🧠 AI Engine (Python 3.13)"]:::ai
    end

    subgraph DataLayer
        PG1[("PostgreSQL Expense DB")]:::database
        PG2[("PostgreSQL Productivity DB")]:::database
    end

    FE -->|"REST/JSON"| GW
    GW -->|"HTTP Routing"| ES
    GW -->|"HTTP Routing"| PS
    ES -->|"gRPC/Protobuf"| AI
    PS -->|"gRPC/Protobuf"| AI
    ES -->|"EF Core"| PG1
    PS -->|"EF Core"| PG2

Loading

---

⚡ Tech Stack & Engineering Principles

Layer	Technology	Patterns & Practices
Frontend	Next.js 15, TypeScript (strict), React Server Components	Server-first rendering, optimistic UI, typed API clients
API Gateway	.NET 10, YARP	Centralized routing, request aggregation, API versioning
Backend Services	.NET 10, EF Core, LiteBus, FluentValidation	Clean Architecture, CQRS, DDD, Vertical Slice, Repository + UoW
AI Engine	Python 3.13, FastAPI, gRPC, Pydantic v2	Pipeline-based processing, async-first, schema validation
Communication	gRPC (inter-service), REST/JSON (client-facing)	Protobuf contracts, retry policies, circuit breakers
Data	PostgreSQL, EF Core Migrations	DB-per-service, no lazy loading, explicit transactions
Observability	Serilog, structured JSON logging	Correlation IDs, distributed tracing readiness
Containerization	Docker, Docker Compose	Multi-stage builds, health checks, network isolation
Orchestration	Kubernetes manifests	Deployments, Services, StatefulSets, ConfigMaps, HPA-ready
Testing	xUnit, FluentAssertions, Moq, pytest, pytest-asyncio	Unit · Integration · Contract tests across all layers

🎯 Architectural Pillars

• 12-Factor App Compliance — environment-driven configuration, stateless services, port binding, dev/prod parity
• Domain-Driven Design — bounded contexts, aggregate roots, value objects, domain events
• CQRS — command/query segregation with dedicated handlers, no business logic in controllers
• Clean Architecture — framework-independent domain, dependency inversion at every boundary
• Cloud-Native — container-first, horizontally scalable, orchestration-ready with Kubernetes
• Contract-First APIs — Protobuf for service communication, OpenAPI for client-facing endpoints

---

📦 Monorepo Structure

self-orbit/
│
├── ai-infrastructure/         # 🧠 Python FastAPI + gRPC AI engine
│   ├── app/
│   │   ├── grpc/              #    Async gRPC server & handlers
│   │   ├── api/               #    REST fallback endpoints
│   │   ├── services/          #    NLP processing services
│   │   ├── pipelines/         #    Composable processing pipelines
│   │   ├── models/            #    Pydantic v2 schemas
│   │   └── core/              #    Config, logging, exceptions
│   └── tests/                 #    pytest + gRPC contract tests
│
├── backend/                   # ⚙️ .NET 10 microservices
│   ├── gateway/               #    YARP API Gateway
│   ├── services/
│   │   ├── expense-service/   #    💰 Financial tracking & budgeting
│   │   └── productivity-service/  📅 Tasks & journal management
│   ├── building-blocks/       #    Shared domain/application/infra
│   ├── tests/                 #    xUnit test projects
│   └── openapi/               #    OpenAPI specifications
│
├── frontend/                  # 🖥️ Next.js 15 TypeScript app
│   ├── app/
│   │   ├── dashboard/        #    Dashboard overview
│   │   ├── expenses/         #    💰 Expense tracking
│   │   ├── tasks/            #    📋 Task management
│   │   ├── journal/          #    📓 Journal entries
│   │   └── dev-tools/        #    🛠️ Developer utilities
│   ├── components/
│   │   ├── layout/          #    Layout components (sidebar, nav)
│   │   └── dev-tools/        #    Data formatters, calculators, prompt library
│   ├── services/              #    Typed API service layer
│   └── types/                 #    TypeScript interfaces
│
├── contracts/                 # 🔗 Shared Protobuf definitions
│   └── proto/                 #    gRPC service contracts
│
├── k8s/                       # ☸️ Kubernetes manifests
├── docs/                      # 📘 Architecture & ADRs
├── scripts/                   # 🔧 Build & dev automation
├── nx.json                    # ⚙️ Nx Workspace configuration
├── docker-compose.yml         # 🐳 Local orchestration
└── docker-compose.override.yml

---

🚀 Quick Start

Prerequisites

• .NET 10 SDK
• Python 3.13+
• Node.js 20+
• Docker & Docker Compose
• Protocol Buffers Compiler

Local Development (via Nx)

This repository uses Nx to orchestrate tasks across Python, .NET, and Next.js.

# Clone the repository
git clone https://github.com/yourusername/self-orbit.git
cd self-orbit

# Install Nx & dependencies
npm install

# Start infrastructure (PostgreSQL)
docker-compose up -d postgres-expense postgres-productivity

# Generate protobuf stubs
./scripts/generate-protos.ps1

# Start the full stack locally via Nx
npm run dev:ai            # Starts Python AI Engine
npm run dev:frontend      # Starts Next.js app
# (Run .NET services through Visual Studio / Rider, or dotnet cli)

# Visualize workspace dependencies
npm run graph

Docker Compose (Full Stack)

docker-compose up --build

Running Tests (via Nx)

# Run tests for all projects across all languages
npm run test:all

# Run tests only for projects affected by your current changes
npm run affected:test

Building Projects

# Build all projects in the correct dependency order
npm run build:all

# Build only affected projects
npm run affected:build

---

🔗 Service Communication & Frontend Navigation

Route	Protocol	Description
Frontend → Gateway	REST/JSON	All client-facing API calls
Gateway → Expense Service	HTTP	Request routing via YARP
Gateway → Productivity Service	HTTP	Request routing via YARP
Expense Service → AI Engine	gRPC/Protobuf	Expense parsing & categorization
Productivity Service → AI Engine	gRPC/Protobuf	Task parsing, transcription, summarization

Frontend Routes (App Router)

Route	Description
/	Redirects to /dashboard
/dashboard	Overview of all modules (expenses, tasks, journal)
/expenses	💰 Expense tracking with AI-powered entry
/tasks	📋 Task management with natural language parsing
/journal	📓 Journal entries with audio transcription
/dev-tools	🛠️ Developer utilities (formatters, calculators, prompt library)

---

🛠️ Dev Tools Module

A collection of browser-based developer utilities accessible at /dev-tools. All tools execute entirely client-side with no backend dependencies.

Data Formatters & Converters

Tool	Description
JSON Formatter / Validator	Beautifies messy strings and validates syntax
Base64 Encoder/Decoder	Converts text or images to Base64 and back
JWT Debugger	Decodes JSON Web Tokens to view header and payload data
SQL Formatter	Prettifies raw SQL queries for readability
URL Encoder/Decoder	Handles special characters for web addresses
YAML ↔ JSON	Switches configuration formats instantly
Unix Timestamp Converter	Converts Epoch time to human-readable dates

Calculators & Logic Tools

Tool	Description
Programmer's Calculator	Handles Hexadecimal, Binary, Octal, and Decimal math
Bitwise Calculator	Performs AND, OR, XOR, and Bit-shift operations
CRON Expression Parser	Explains cron schedules in plain English, shows next runs
CSS Unit Converter	Converts PX to REM, EM, or VH/VW
Regex Tester	Tests and explains regular expressions in real-time
Diff Checker	Compares two text blocks to highlight code differences

Prompt Library

• Variable Injection: Prompts with {{variable}} placeholders for quick filling
• Template Versioning: Save and restore different versions of prompts
• Categorized Folders: Organize prompts by task (e.g., Refactoring, Unit Tests)
• Context Snippets: Store reusable system instructions or style guides

Keyboard Shortcuts: Ctrl+K to open search, Escape to return to tool grid.

Data Persistence: Prompts and snippets stored in localStorage under keys self-orbit:prompt-library and self-orbit:prompt-snippets.

---

📊 API Endpoints

Expense Service

Method	Endpoint	Description
POST	/api/v1/expenses	Create expense (triggers AI parsing)
GET	/api/v1/expenses	List expenses with filters
GET	/api/v1/expenses/{id}	Get expense by ID
POST	/api/v1/budgets	Set budget for category/period
GET	/api/v1/budgets	List active budgets

Productivity Service

Method	Endpoint	Description
POST	/api/v1/tasks	Create task (triggers AI parsing)
GET	/api/v1/tasks	List tasks with filters
PATCH	/api/v1/tasks/{id}/status	Transition task state
POST	/api/v1/journal	Create journal entry
POST	/api/v1/journal/audio	Upload audio for transcription
GET	/api/v1/journal	List journal entries

---

☸️ Kubernetes Deployment

# Apply all manifests
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/ --recursive

# Verify deployments
kubectl get pods -n self-orbit
kubectl get services -n self-orbit

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

_{Built with ❤️ as a showcase of enterprise-grade microservice architecture, cloud-native engineering, and full-stack AI integration.}