diff --git a/README.md b/README.md
index d13cbfe..d6fdc26 100644
--- a/README.md
+++ b/README.md
@@ -1,98 +1,157 @@
-# DevBits
+
+ 
+
-A place for developers to share their projects.
+DevBits
-Goal: Create an X and LinkedIn crossover for posting real content about your projects, semi-formally
+
+ Social infrastructure for builders shipping in public.
+
-### Outline
+
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+
-Projects are the baseline of the app, you must have a project to post.
+---
-Anyone can comment, like, follow, despite their project count.
+
+ 
+
-Some quirky names for things (frontend only)
+## Product Identity
-- Projects are called 'Stream's
-- Posts about projects are called 'Byte's
-- Comments are called 'Bit's
+DevBits is where developers document real progress, not vanity metrics.
-### Tech Stack
+- `Streams` are projects.
+- `Bytes` are project updates.
+- `Bits` are comments and conversations.
-- Backend/API in Go using Gin framework
-- Frontend: ReactNative (iOS and Android)
-- Database: PostgreSQL
-- Host: AWS ec2 for backend, AWS RDS for PostgreSQL
+Anyone can react, follow, comment, and join the conversation.
-## Local Development
+> [!IMPORTANT]
+> DevBits is designed for technical storytelling: milestones, blockers, experiments, demos, and lessons learned.
-### Quick Start
+## Visual Gallery
-Start only the frontend (choose production or local backend at launch):
+| Home Feed | Discovery |
+| --- | --- |
+| 
| 
|
-```bash
-./run-front.sh
-```
+| Streams | Messaging |
+| --- | --- |
+| 
| 
|
-Start local backend stack only (dev PostgreSQL + backend):
+| Profile | Product Motion |
+| --- | --- |
+| 
| 
|
-```bash
-./run-dev.sh
-```
+## Experience Cards
-Then start frontend and choose local or live backend:
+| Card | What It Delivers |
+| --- | --- |
+| `Build Logs` | Structured public progress for each project stream, from first prototype to launch day. |
+| `Discovery Engine` | Explore recent streams, bytes, people, and tags in one place. |
+| `Builder Identity` | Profiles, follows, saved streams, saved bytes, and creator-centric timelines. |
+| `Real Conversations` | Direct messages, threaded discussions, and comment-level collaboration. |
+| `Creation Flow` | Quick post publishing with media support and stream-first organization. |
-```bash
-./run-front.sh
-```
+## App Functions
-Run backend tests using dockerized Go against the dev DB stack:
+
+ ▸ Core social model
+
-```bash
-./run-db-tests.sh
-```
+- Stream-first posting model: project context is always attached to updates.
+- Byte interactions: reactions, saves, and threadable discussion.
+- Follow graph for people discovery and relationship context.
+- Unified feed surfaces both streams and bytes.
-PowerShell equivalents:
+
-```powershell
-.\run-front.ps1
-.\run-dev.ps1
-.\run-db-tests.ps1
-```
+
+ ▸ Discovery and navigation
+
+
+- Dedicated Explore experience for users, tags, streams, and bytes.
+- Category-aware search and trend-style tag surfacing.
+- Route-based architecture with tabs and deep-linked detail pages.
+- Welcome tour introduces product primitives and navigation model.
+
+
+
+
+ ▸ Builder profile system
+
-Scan the QR code with Expo Go on your phone. The app will automatically connect to your local backend.
+- Personal stream portfolio with project and post collections.
+- Follower/following views and interaction controls.
+- Saved content libraries for both streams and bytes.
+- Profile metadata and social proof around shipping activity.
-### Verification Checklist
+
-- Fresh clone frontend check: run `chmod +x run-front.sh run-dev.sh run-db-tests.sh`, then `./run-front.sh`, choose `Production`, and confirm Expo starts.
-- Backend stack: run `./run-dev.sh`, confirm backend health at `http://:8080/health`.
-- Frontend to local backend: run `./run-front.sh --local`, then validate app API calls from a phone on same WiFi.
-- DB tests: run `./run-db-tests.sh` and confirm it exits with code `0`.
+
+ ▸ Messaging and collaboration
+
-### Prerequisites
+- Direct message threads by builder.
+- Username search with suggestion ranking.
+- Conversation-level interaction for async collaboration.
-1. Install Docker and Docker Compose (v2)
-2. Install Node.js/npm for Expo frontend
+
-### Troubleshooting
+
+ ▸ Platform and delivery
+
-- Docker Desktop on Windows: ensure file sharing is enabled for the repo path.
-- If `8080` or `5433` is occupied, the scripts prompt for alternate ports (or allow exit with guidance).
-- WSL/Docker Desktop/Linux engine differences: run scripts from the environment that owns your Docker daemon and ensure localhost port forwarding is enabled.
+- Go + Gin REST backend with JWT auth and middleware-protected routes.
+- PostgreSQL production database and SQLite-friendly test workflows.
+- React Native + Expo mobile client for Android and iOS.
+- AWS-hosted backend deployment path.
+
+
+
+## Language and Platform Snapshot
+
+```text
+Backend: Go (Gin API, JWT auth, DB query layer)
+Frontend: TypeScript (React Native + Expo Router)
+Database: PostgreSQL (production), SQLite (test mode)
+Infra: AWS EC2 + AWS RDS
+```
+
+## Architecture at a Glance
+
+```mermaid
+flowchart LR
+ A[Mobile App\nReact Native + Expo] --> B[Go API\nGin]
+ B --> C[(PostgreSQL)]
+ B --> D[Media Uploads]
+ A --> E[Streams / Bytes / Bits UX]
+```
-For detailed instructions, see [INSTRUCTIONS.md](INSTRUCTIONS.md).
+## Project Story
-## Static file sync
+DevBits exists to make technical progress visible.
-`backend/api/static/` is the source of truth for compliance and deep-linking files
-(`apple-app-site-association`, `privacy-policy.html`, `account-deletion.html`).
-The same files are mirrored into `frontend/public/` for the Expo web build.
+Instead of posting polished outcomes only, builders can share:
-Run `Bash-Scripts/sync-static.sh` after editing any file in `backend/api/static/`
-to keep the frontend copy in sync.
+- What they are building now
+- What broke today
+- What they learned while fixing it
+- What they are shipping next
-## Deployment DB scripts
+> [!TIP]
+> The goal is simple: give developers a social home for real work in progress.
-All deployment database script commands and usage are documented in:
+## Explore More
-- [backend/scripts/README.md](backend/scripts/README.md)
-- [backend/docs/AWS_TRANSFER_NO_NGINX.md](backend/docs/AWS_TRANSFER_NO_NGINX.md)
+- Product and deployment runbook: [INSTRUCTIONS.md](INSTRUCTIONS.md)
+- Backend structure and scripts: [backend/scripts/README.md](backend/scripts/README.md)
+- AWS deployment notes: [docs/AWS_TRANSFER_NO_NGINX.md](docs/AWS_TRANSFER_NO_NGINX.md)