📁 Project Structure

Guía para entender dónde está cada cosa en Aeternus.

🏗️ Folder Layout

aeternus/
├── src/                          # ⚛️ Frontend (Next.js + React)
│   ├── app/
│   │   ├── layout.tsx           # Main layout
│   │   ├── page.tsx             # Home page
│   │   ├── chat/               # Chat module
│   │   ├── admin/              # Admin dashboard
│   │   └── api/                # Next.js API routes
│   ├── components/             # React components
│   ├── hook/                   # Custom hooks
│   ├── lib/                    # Libraries & integrations
│   └── utils/                  # Utility functions
│
├── core/                         # 🐍 Backend (FastAPI + Python)
│   ├── app/
│   │   ├── main.py             # Entry point
│   │   ├── routes/             # API endpoints
│   │   ├── schemas.py          # Data models
│   │   └── settings.py         # Config
│   ├── Dockerfile
│   ├── requirements.txt
│   └── .env
│
├── prisma/                       # 💾 Database Schema
│   └── schema.prisma
│
├── docs/                         # 📚 Documentation
│   ├── setup-local.md
│   ├── environment-variables.md
│   └── ...
│
└── .github/workflows/            # 🤖 CI/CD

---

Key Directories

src/app/

Next.js App Router — Each folder with page.tsx = a route.

• src/app/page.tsx → /
• src/app/chat/page.tsx → /chat
• src/app/admin/page.tsx → /admin

src/components/

React Components — Reusable, not tied to routes.

• chat/ — Chat-related components
• admin/ — Admin dashboard components
• navbar/ — Navigation
• etc.

src/hook/

Custom React Hooks — named with use* prefix.

• useChat.ts — Chat logic hook
• useAuth.ts — Auth logic hook

core/app/routes/

FastAPI Endpoints — Each file groups related endpoints.

• chat.py — POST /v1/chat, POST /v1/chat/stream
• chat_storage.py — POST /api/chat/save, etc.
• tts.py — GET/POST /api/tts
• health.py — GET /v1/health

prisma/

Database Schema — Define your data models here.

• schema.prisma — User, Conversation, Message, etc.

---

Adding New Features

Add a new page

mkdir -p src/app/my-page
cat > src/app/my-page/page.tsx <<EOF
export default function MyPage() {
  return <div>My Page</div>;
}
EOF

Accessible at /my-page

Add a new API endpoint

# In core/app/routes/my_route.py
from fastapi import APIRouter

router = APIRouter()

@router.post("/api/my-endpoint")
async def my_endpoint(request: MyRequest):
    return {"status": "ok"}

Then register in core/app/main.py:

from app.routes import my_route
app.include_router(my_route.router)

Add a database table

# In prisma/schema.prisma
model MyTable {
  id    String  @id @default(cuid())
  name  String
  email String  @unique
}

Then migrate:

npx prisma migrate dev --name add_my_table

---

Data Flow

Chat Message Flow

ChatInput → Chat Hook → fetch(/v1/chat) → Backend
             ↓
         setState with response
             ↓
         Re-render ChatMessage
             ↓
         Display response

Save to Database

ChatInput → save() → POST /api/chat/saveMessage
                     ↓
                 Backend validates (Pydantic)
                     ↓
                 Save to PostgreSQL (Prisma)
                     ↓
                 Return success

---

Technology Stack

Layer	Technology
Frontend	Next.js 14, React 18, TypeScript
Styling	Tailwind CSS, HeroUI
Backend	FastAPI, Python 3.9+
Database	PostgreSQL, Neo4j, Prisma ORM
Auth	Auth0
AI	OpenAI API
Deploy	Vercel, AWS ECS

---

Important Files

• src/app/layout.tsx — Main layout & navigation
• src/app/page.tsx — Home page
• src/components/chat/Chat.tsx — Chat component
• core/app/main.py — Backend entry point
• prisma/schema.prisma — Database schema
• .env.local — Frontend config
• core/.env — Backend config
• mkdocs.yml — Documentation config

---

Next Steps

1. Read Setup Local
2. Read Contributing
3. Explore the code!