instagram-clone/SPEC.md

Project: Instagram Clone (SocialPhoto)

Overview

SocialPhoto es un clon minimalista de Instagram que prioriza la simplicidad y velocidad. Permite a usuarios registrarse, subir imágenes, interactuar con publicaciones (likes/dislikes), comentar y seguir a otros usuarios. Ideal para testing de agentes de IA.

Principios:

• Simple de instalar y operar
• Base de datos portable (SQLite)
• API RESTful clara y documentada
• En desarrollo: migrar a PostgreSQL en producción

---

Architecture

Components

• FastAPI Backend: Python 3.11+ REST API
• SQLite Database: Almacenamiento local para desarrollo
• JWT Authentication: Auth via tokens Bearer
• Local File Storage: Imágenes almacenadas en /uploads
• Static Files: Avatar default, served estáticamente

Data Model

Users

Field	Type	Description
id	INTEGER	Primary key
username	TEXT	Unique, required
email	TEXT	Unique, required
password_hash	TEXT	bcrypt hashed
avatar_url	TEXT	URL to avatar
bio	TEXT	User biography
created_at	TIMESTAMP	Creation date

Posts

Field	Type	Description
id	INTEGER	Primary key
user_id	INTEGER	FK to users
image_path	TEXT	Path to uploaded image
caption	TEXT	Post caption
created_at	TIMESTAMP	Creation date

Comments

Field	Type	Description
id	INTEGER	Primary key
post_id	INTEGER	FK to posts
user_id	INTEGER	FK to users
content	TEXT	Comment text
created_at	TIMESTAMP	Creation date

Likes/Dislikes

Field	Type	Description
id	INTEGER	Primary key
post_id	INTEGER	FK to posts
user_id	INTEGER	FK to users
created_at	TIMESTAMP	Creation date

Follows

Field	Type	Description
id	INTEGER	Primary key
follower_id	INTEGER	FK to users
following_id	INTEGER	FK to users
created_at	TIMESTAMP	Creation date

---

Tech Stack

Component	Technology
Backend	Python 3.11+ con FastAPI
Database	SQLite3 (dev), PostgreSQL (prod)
Auth	JWT (python-jose)
Password	bcrypt
Migrations	Alembic
Testing	pytest + pytest-asyncio + httpx
Upload	Local storage in /uploads

---

API Endpoints

Authentication

Method	Endpoint	Description
POST	/auth/register	Register new user
POST	/auth/login	Login, returns JWT

Users

Method	Endpoint	Description
GET	/users/{id}	Get user profile
GET	/users/{id}/posts	Get user's posts
GET	/users/{id}/stats	Get user stats
POST	/users/{id}/follow	Follow user
DELETE	/users/{id}/follow	Unfollow user

Posts

Method	Endpoint	Description
POST	/posts	Create post (multipart with image)
GET	/posts	Global feed
GET	/posts/{id}	Get post details
DELETE	/posts/{id}	Delete post (owner only)
POST	/posts/{id}/like	Like post
DELETE	/posts/{id}/like	Remove like
POST	/posts/{id}/dislike	Dislike post
DELETE	/posts/{id}/dislike	Remove dislike

Comments

Method	Endpoint	Description
GET	/posts/{id}/comments	List comments
POST	/posts/{id}/comments	Add comment
DELETE	/comments/{id}	Delete comment (owner only)

Feed

Method	Endpoint	Description
GET	/feed	Personal feed (following)
GET	/feed/global	Global feed

---

Project Structure

instagram-clone/
├── app/
│   ├── __init__.py
│   ├── main.py           # FastAPI app entry
│   ├── config.py         # Settings
│   ├── database.py       # SQLite connection + setup
│   ├── models.py         # Pydantic models
│   ├── auth.py           # JWT helpers
│   ├── routes/
│   │   ├── __init__.py
│   │   ├── auth.py       # /auth/* endpoints
│   │   ├── users.py      # /users/* endpoints
│   │   ├── posts.py      # /posts/* endpoints
│   │   └── comments.py   # /comments/* endpoints
│   └── services/
│       ├── __init__.py
│       └── social.py     # Social logic (likes, follows)
├── uploads/              # Image storage
├── alembic/              # DB migrations
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_auth.py
│   ├── test_posts.py
│   └── test_social.py
├── requirements.txt
├── alembic.ini
├── SPEC.md
└── README.md

---

Acceptance Criteria

Auth

• User can register with username, email, password
• User can login and receive JWT
• Protected routes require valid token
• No duplicate username/email allowed

Posts

• User can create post with image and caption
• Global feed shows all posts ordered by date
• Personal feed shows only followed users' posts
• User can delete their own posts

Likes / Dislikes

• User can like a post
• User can dislike a post
• Like and dislike are mutually exclusive
• Like/dislike counts update in real-time

Comments

• User can comment on a post
• User can delete their own comments
• Comments include username and timestamp

Follow

• User can follow another user
• User can unfollow
• Cannot follow self
• Stats show followers/following count

---

Out of Scope

• No real-time notifications (WebSocket)
• No direct messages
• No stories/reels
• No algorithm-based feed
• No image compression/resizing