You are a highly skilled AI full-stack developer tasked with creating a single-page application (SPA) for a decentralized social network based on the sAT Protocol. The goal is to provide users with a private, self-reliant social networking experience where they control their data. This SPA will act as a client for the sAT Protocol, interacting with user-hosted static sites.
**1. PROJECT OVERVIEW:**
The sAT Protocol enables decentralized social networking over static sites. Users host their encrypted JSON data on their own static websites (e.g., GitHub Pages, Netlify, Vercel, or custom domains). This application, codenamed 'Saturn Social', will serve as a user-friendly client for this protocol. It will allow users to aggregate feeds from their own and others' static sites, post content, and interact socially without relying on central servers or relays. The core value proposition is user data ownership, enhanced privacy through encryption, censorship resistance, and a simplified, self-reliant social experience.
**2. TECH STACK:**
* **Frontend Framework:** React (using functional components and Hooks)
* **Styling:** Tailwind CSS for rapid UI development and a consistent design system.
* **State Management:** Zustand for efficient and simple global state management. It's lightweight and fits well with the SPA architecture.
* **Routing:** React Router DOM for client-side navigation within the SPA.
* **HTTP Client:** `fetch` API or `axios` for interacting with the user's static site data (local JSON files or fetched via URLs).
* **Utilities:** Lodash for utility functions, Crypto-js for basic encryption/decryption if client-side encryption handling is needed (though the protocol assumes data is already encrypted).
* **Build Tool:** Vite for fast development server and optimized builds.
**3. CORE FEATURES & USER FLOWS:****
* **Profile Setup & Connection:**
* **User Flow:** Upon first launch, the user is prompted to enter the URL of their static site where their sAT data resides. They might also need to specify the path to their sAT data (e.g., `/satellite/` or a custom path defined in `.well-known/satproto.json`). The client then attempts to fetch the user's profile information and initial posts from this URL.
* **Details:** This involves fetching a configuration file (if applicable, like `.well-known/satproto.json`) and then the main user data JSON.
* **Feed Aggregation:**
* **User Flow:** The main view displays a chronological feed of posts from the user and any other users they follow (following will be implemented by manually adding the URLs of friends' static sites).
* **Details:** The client fetches data from configured user URLs, aggregates posts, sorts them by timestamp, and displays them. It needs to handle potential errors during data fetching (e.g., site not found, invalid data format).
* **Post Creation:**
* **User Flow:** A dedicated section or modal allows users to compose a new post. Upon submission, the post is encrypted, formatted as JSON, and the client provides instructions or attempts to update the user's static site data (this might require manual upload or a more advanced integration if the static site hosting supports it).
* **Details:** Input field for post content, character count, encryption of content, JSON formatting, and outputting the updated data structure. For MVP, the client can generate the JSON payload for the user to manually upload or commit to their repo.
* **Social Interactions (Likes/Comments):**
* **User Flow:** Users can 'like' posts or add comments. These interactions are also treated as posts linked to the original content and are published to the user's own static site.
* **Details:** Interactions are appended to the user's data store. The client needs to associate these interactions with the original post ID and author.
* **Following/Friends Management:**
* **User Flow:** Users can add the URLs of friends' static sites to their configuration. The client will then fetch and display posts from these added URLs.
* **Details:** A simple list in the settings or configuration area where users can add/remove friend site URLs.
**4. UI/UX DESIGN:****
* **Layout:** A clean, minimalist, single-column layout for the main feed. A sidebar or top navigation for profile, posting, settings, and friends management. Focus on content readability.
* **Color Palette:** A calm and modern palette. Primary: Dark charcoal (`#1a1a1a`) for background. Secondary: Off-white (`#f0f0f0`) for text. Accent: A subtle teal or muted blue (`#4dc0b5`) for interactive elements and links. Use shades of gray for secondary information.
* **Typography:** A clean, sans-serif font like Inter or Lato for body text and headings. Ensure good contrast and legibility.
* **Responsive Design:** Mobile-first approach. The layout should adapt seamlessly to various screen sizes (smartphones, tablets, desktops). Use flexbox and grid extensively. Ensure touch targets are adequately sized on mobile.
* **Key Components:** Feed list, Post card, New Post composer, Profile view, Settings panel, Friend list.
**5. DATA MODEL:**
* **`UserProfile`:**
```json
{
"userId": "string (unique identifier, could be hash of public key)",
"username": "string",
"bio": "string",
"avatarUrl": "string (URL to avatar image)",
"staticSiteUrl": "string (user's primary static site URL)",
"satProtoPath": "string (optional, path to satproto.json if not default)"
}
```
* **`Post`:**
```json
{
"postId": "string (unique identifier)",
"authorId": "string (userId of the author)",
"timestamp": "number (Unix timestamp)",
"content": "string (encrypted content)",
"type": "string (e.g., 'post', 'like', 'comment')",
"replyTo": "string (optional, postId if it's a reply/comment)",
"likes": ["string (userIds who liked this post)"]
}
```
* **`AppState` (Zustand Store):**
```javascript
{
currentUser: UserProfile | null,
feed: Post[],
friends: UserProfile[],
currentPostContent: string,
isLoading: boolean,
error: string | null
}
```
* **Local Storage:** Store `currentUser` profile, `friends` list, and potentially fetched `feed` data for offline access or faster loading.
**6. COMPONENT BREAKDOWN:**
* **`App.jsx`:** Main application component, sets up routing and global layout.
* **`Feed.jsx`:** Displays the aggregated list of posts. Fetches data, manages loading/error states.
* Props: `posts` (array of Post objects)
* **`PostCard.jsx`:** Renders a single post.
* Props: `post` (Post object), `onLike` (function), `onComment` (function)
* **`PostComposer.jsx`:** Form for creating new posts.
* Props: `onSubmit` (function), `initialContent` (string, optional)
* **`ProfileView.jsx`:** Displays user profile information.
* Props: `user` (UserProfile object)
* **`Settings.jsx`:** Manages user settings, including adding/removing friend site URLs.
* **`FriendList.jsx`:** Displays the list of followed users.
* Props: `friends` (array of UserProfile objects)
* **`Header.jsx`:** Top navigation bar.
* **`Footer.jsx`:** Application footer.
* **`LoadingSpinner.jsx`:** Reusable loading indicator.
* **`ErrorMessage.jsx`:** Reusable error display component.
**7. ANIMATIONS & INTERACTIONS:****
* **Feed Transitions:** Subtle fade-in animation for new posts loading into the feed.
* **Button Hover Effects:** Slight scale or color change on interactive elements (buttons, links) on hover using Tailwind's `hover:` variants.
* **Loading States:** Display `LoadingSpinner` component when fetching data or submitting posts. Show skeleton loaders for feed items before content is loaded.
* **Micro-interactions:** Visual feedback when a 'like' button is clicked (e.g., icon fill animation).
* **Form Validation Feedback:** Subtle animation or styling changes to indicate input errors.
**8. EDGE CASES:****
* **Empty States:** Display user-friendly messages when the feed is empty, no friends are added, or profile data cannot be fetched (e.g., 'Your feed is empty. Start by adding a friend!' or 'Could not load profile data. Please check your static site URL.').
* **Error Handling:** Gracefully handle network errors, invalid JSON responses, and encryption/decryption failures. Display informative error messages to the user without crashing the app.
* **Data Validation:** Validate fetched JSON data against expected schemas. Implement client-side validation for post content before attempting encryption/submission.
* **Accessibility (a11y):** Use semantic HTML elements, provide ARIA attributes where necessary, ensure sufficient color contrast, and make the application navigable via keyboard.
* **Protocol Adherence:** Ensure the client correctly parses `.well-known/satproto.json` if present and handles the specified data paths.
* **Initial Load:** Manage the initial state where no user data or friends are configured.
**9. SAMPLE DATA:**
* **`user1_profile.json` (Example hosted at `https://user1.github.io/satellite/profile.json`):**
```json
{
"userId": "u123abc",
"username": "Alice Wonderland",
"bio": "Exploring the rabbit hole. Tech enthusiast. Lover of static sites.",
"avatarUrl": "https://user1.github.io/assets/avatar.png",
"staticSiteUrl": "https://user1.github.io"
}
```
* **`user1_posts.json` (Example hosted at `https://user1.github.io/satellite/posts.json`):**
```json
[
{
"postId": "p1",
"authorId": "u123abc",
"timestamp": 1678886400,
"content": "eyJrZXkiOiJ2YWx1ZSIsInR5cGUiOiJhZ2VuY3kifQ==", // Encrypted content example
"type": "post",
"likes": ["u456def"]
},
{
"postId": "p2",
"authorId": "u123abc",
"timestamp": 1678972800,
"content": "eyJrZXkiOiJ2YWx1ZSIsInR5cGUiOiJhZ2VuY3kifQ==",
"type": "comment",
"replyTo": "p3",
"likes": []
}
]
```
* **`user2_profile.json` (Example hosted at `https://user2.github.io/profile.json`):**
```json
{
"userId": "u456def",
"username": "Bob The Builder",
"bio": "Building cool things with code and coffee.",
"avatarUrl": "https://user2.github.io/images/bob.jpg",
"staticSiteUrl": "https://user2.github.io",
"satProtoPath": "my-sat-data"
}
```
* **`user2_posts.json` (Example hosted at `https://user2.github.io/my-sat-data/posts.json`):**
```json
[
{
"postId": "p3",
"authorId": "u456def",
"timestamp": 1678900000,
"content": "eyJrZXkiOiJ2YWx1ZSIsInR5cGUiOiJhZ2VuY3kifQ==",
"type": "post",
"likes": ["u123abc"]
}
]
```
* **`.well-known/satproto.json` (Example for User 2):**
```json
{
"sat_root": "my-sat-data"
}
```
**10. DEPLOYMENT NOTES:****
* **Build Command:** Use `npm run build` or `yarn build` (via Vite) to create an optimized production build. The output will be in a `dist` folder.
* **Environment Variables:** Use `.env` files for development and production. Key variables might include API base URLs if external services are ever integrated (though the core idea is no external services).
* **Static Site Hosting:** The built SPA (HTML, CSS, JS files) should be deployed to a static hosting provider (like Netlify, Vercel, GitHub Pages). For the sAT protocol itself, users host their JSON data on their chosen static hosting.
* **Performance Optimizations:** Leverage Vite's built-in optimizations (code splitting, tree shaking). Implement lazy loading for components and images where appropriate. Minimize bundle size. Cache fetched data effectively using Zustand's state management and potentially `localStorage`.
* **HTTPS:** Ensure the SPA is served over HTTPS, especially if any sensitive local storage is used.
* **CORS:** Not applicable in the traditional sense as the client fetches data from origins the user explicitly trusts (their own static site or friends' sites). However, ensure the client correctly handles requests to different subpaths or domains.
* **Error Reporting:** Integrate a lightweight error reporting service (e.g., Sentry for client-side errors) if desired, but be mindful of adding external dependencies.