Traductor Técnico para Documentación de Proyectos en Lenguaje Claro

# FORME.md - ${name} ## 1. The Big Picture ${name} is a platform that [restate the one-sentence description in plain language]. In short: [expand into 2-3 more sentences explaining the core value and who it serves]. **What problem does this solve, and for whom?** [Plain-language explanation of the problem and target user. Example: "Restaurant owners lose 30% of every order to delivery aggregators. This platform gives them their own online ordering system so customers order directly - and the restaurant keeps the full margin."] **How do users interact with it?** [Walk through the user journey in plain words. Example: "A customer lands on the restaurant's own website, browses the menu, adds items to a cart, pays, and gets a confirmation. The restaurant sees the order on a dashboard, prepares it, and marks it ready. That's it - no middleman."] **If this were a restaurant...** [One consistent analogy for the whole system. Example: "Imagine ${name} as a restaurant. The **frontend** is the dining room - it's what customers see and touch. The **API layer** is the kitchen - orders come in, get processed, and food goes out. The **database** is the walk-in fridge - everything is stored there. The **payment processor** is the cash register - it handles money securely. And the **admin dashboard** is the manager's office - it's where you see how the whole place is running."] --- ## 2. Technical Architecture - The Blueprint [Simple text diagram of the architecture. Example:] ``` [User's Browser] | v [Frontend (Next.js)] ----> [API Layer (Next.js routes)] | | | v | [Database (Supabase)] | | | v | [External Services] | (Payments, Email, etc.) | v [Admin Dashboard] ``` **A tour of the building:** **This is the front door (Frontend).** [Explain what the frontend does, who uses it, and why it's built this way. Example: "This is everything users see - the menu, the cart, the checkout page. It's built with Next.js, which means pages load fast because the server pre-builds them. Think of it like a restaurant that preps ingredients before you arrive - you get your food faster."] **This is the kitchen (API Layer).** [Explain what the API does, why it exists as a separate layer, and what happens here. Example: "All the real work happens here. When a user places an order, the frontend sends a request to the API. The API validates it, checks the database, processes payment, and sends back a response. It's the kitchen - the frontend just takes the order, but the kitchen actually cooks it."] **This is the walk-in fridge (Database).** [Explain the database, what's stored there, and why it's structured this way. Example: "Every menu item, user account, order, and payment record lives here. We use Supabase, which is a hosted Postgres database - think of it as a professional-grade fridge that's managed by someone else, so we don't have to worry about maintaining it ourselves."] **This is the cash register (External Services).** [Explain integrations like Stripe, email services, etc. Example: "When a customer pays, we don't handle the credit card ourselves - that would be like keeping cash in a shoebox under the counter. Instead, we use Stripe, which is a professional payment processor. They handle the money, we get notified when it's done."] **Why this architecture and not something simpler?** [Explain the reasoning. Example: "We could have built everything into one giant file - and for a tiny project, that works. But as the platform grows, separating the frontend from the API means we can scale them independently. If 10,000 people are browsing menus but only 100 are placing orders, we can beef up the frontend servers without touching the kitchen."] **Clever or unusual choices:** [Highlight anything notable. Example: "One thing you'll notice is that we use the same Next.js app for both the customer-facing site and the admin dashboard. That's unusual - most projects split them. We did it to keep deployment simple: one app, one server, one place to update. The trade-off is that the admin dashboard and customer site share infrastructure, so a heavy traffic spike on one could slow down the other."] --- ## 3. Codebase Structure - The Filing System [Folder tree, top 2-3 levels. Example:] ``` ${name}/ ├── app/ # The main application │ ├── api/ # API routes (the kitchen) │ ├── admin/ # Admin dashboard pages │ ├── (auth)/ # Login/signup pages │ └── page.tsx # The landing page ├── components/ # Reusable UI pieces ├── lib/ # Shared utilities ├── public/ # Static assets (images, etc.) ├── supabase/ # Database migrations └── package.json # Project dependencies ``` **What lives where:** **`app/` - The main building.** This is the heart of the project. Every page a user can visit is defined here. If you need to change what a user sees, you'll start here. **`app/api/` - The kitchen.** All the backend logic lives here. When the frontend needs data, it calls these routes. If you need to change how orders are processed, this is where you look. **`components/` - The furniture.** Reusable UI pieces - buttons, forms, cards, modals. If you need to change how a button looks across the whole site, you change it here once and it updates everywhere. **`lib/` - The toolbox.** Shared utilities and helper functions. Things like database connections, formatting helpers, and authentication logic. **`supabase/` - The blueprint archive.** Database migrations - the version history of our database schema. If we need to add a new table or column, the migration lives here. **Non-obvious naming conventions:** [Flag anything confusing. Example: "You'll notice some folders have parentheses in their names, like `(auth)`. That's a Next.js convention - it means the folder doesn't affect the URL. So `(auth)/login` is actually served at `/login`, not `/(auth)/login`. It's just a way to group related pages without cluttering the URL structure."] **Entry points:** [Identify where things start. Example: "The main entry point is `app/page.tsx` - this is the landing page. But the real action starts in `app/api/` - specifically `app/api/orders/route.ts`, which handles order creation. If you're new to the codebase, start by reading `lib/` to understand the shared utilities, then trace a single API route from start to finish."] --- ## 4. Connections & Data Flow - How Things Talk to Each Other ### User Action 1: [e.g., "User signs up"] [Walk through the full journey. Example:] 1. **The user fills out the signup form** on the `/signup` page. The form is built with React - think of it as a paper form that checks its own work before submitting. 2. **The form sends a request to the API** at `app/api/auth/signup/route.ts`. This is like dropping the form in the mail - the frontend doesn't wait around, it just sends the request and listens for a response. 3. **The API validates the input** - checks that the email is formatted correctly, the password is long enough, and the email isn't already taken. This is the kitchen checking that the order makes sense before cooking. 4. **The API creates a user record in the database** via Supabase. The password is hashed - meaning it's scrambled so that even if someone steals the database, they can't read the passwords. Think of it as writing the password in a secret code that only the system can decode. 5. **The API returns a success response** with a session token. This token is like a VIP wristband - it proves the user is who they say they are for the next few hours, so they don't have to log in again on every page. 6. **The frontend stores the token** and redirects the user to their dashboard. **What could go wrong:** If the database is down, the signup fails. The user sees an error message. We could add a retry mechanism, but for now, the user just tries again. ### User Action 2: [e.g., "User places an order"] [Walk through the full journey. Example:] 1. **The user clicks "Place Order"** on the checkout page. The frontend gathers all the cart items, the total, and the user's ID. 2. **The frontend sends a POST request** to `app/api/orders/route.ts`. This is the bell ringing in the kitchen. 3. **The API validates the order** - checks that the user is authenticated (has a valid session token), that the cart isn't empty, and that the total matches what the menu says it should be. This prevents someone from tampering with prices. 4. **The API calls Stripe** to process the payment. This is the cashier running the credit card. Stripe handles the actual money movement - we never see or store the credit card number. 5. **If payment succeeds, the API creates an order record** in the database with status "paid". This is the kitchen writing the order ticket and pinning it to the rail. 6. **The API returns the order details** to the frontend, which shows a confirmation screen. 7. **The restaurant owner sees the new order** on their admin dashboard, which polls the database for new orders (or gets a real-time update via Supabase's subscription feature). **What could go wrong:** If Stripe is down, the payment fails. The order is not created. The user sees an error and can retry. If the database is down, the order might be paid but not recorded - this is the worst case. We handle this by checking the database before charging the card, but there's still a small window where a failure could cause a discrepancy. This is a known limitation. **External service connections:** [List each external service and what happens if it fails. Example:] - **Stripe (payments):** If Stripe is down, no orders can be placed. Users see an error at checkout. We don't have a fallback payment processor - this is a single point of failure. - **Supabase (database/auth):** If Supabase is down, the entire app is down - no logins, no orders, no menu. This is the biggest risk. We chose Supabase because it's reliable, but it's still a third-party dependency. - **[Email service]:** If the email service fails, users don't get confirmation emails, but the core app still works. This is a minor issue. **Authentication flow:** [Explain how auth works. Example: "When a user logs in, the API verifies their credentials against the database. If correct, it issues a JSON Web Token (JWT) - think of it as a stamped ticket with an expiry time. The frontend stores this token and sends it with every request. The API checks the token's signature and expiry before processing anything. This is called 'stateless authentication' - the server doesn't need to remember who's logged in; it just verifies the token each time."] --- ## 5. Technology Choices - The Toolbox | Technology | What It Does Here | Why This One | Watch Out For | |-----------|------------------|--------------|---------------| | **Next.js** | The web framework that powers both the customer site and admin dashboard. It handles routing, server-side rendering, and API routes. | It's the most popular React framework, has excellent performance out of the box, and lets us use one codebase for frontend and backend. We considered separate frontend/backend (like React + Express) but that doubles the deployment complexity. | Next.js updates frequently and major versions can break things. Also, server-side rendering can be confusing when you're debugging - sometimes the code runs on the server, sometimes on the client. | | **React** | The UI library - it builds every component the user sees. | Industry standard, huge ecosystem, and we already knew it. Alternatives like Vue or Svelte are fine, but React has the largest talent pool. | React re-renders can cause performance issues if you're not careful. | | **Supabase** | Hosted Postgres database + authentication + real-time subscriptions. | We chose it over Firebase because it uses SQL (which is more powerful for complex queries) and it's open-source. Firebase is easier to start with but locks you into their ecosystem. Supabase gives us a real database we could migrate off of if needed. | It's a third-party service - if they have an outage, we have an outage. Also, the free tier has limits on concurrent connections and storage. | | **Stripe** | Payment processing - handles credit cards, refunds, and payouts. | The most developer-friendly payment API. Alternatives like PayPal or Braintree are clunkier. Stripe handles PCI compliance so we never touch raw card data. | Stripe takes a percentage of every transaction. Also, their API changes occasionally and can break integrations. | | **Tailwind CSS** | Styling framework - makes the UI look good without writing custom CSS. | Fast to develop with, and it keeps styles consistent. We considered styled-components but Tailwind is more performant and easier to maintain. | The class names make HTML look messy, and there's a learning curve if you're used to traditional CSS. | | **[Any other tech]** | [What it does] | [Why chosen] | [Trade-offs] | --- ## 6. Environment & Configuration **Environment variables:** [Explain each variable in plain language. Example:] | Variable | What It Controls | What Happens If It's Wrong | |----------|-----------------|---------------------------| | `DATABASE_URL` | The address of the database - like the street address of the walk-in fridge. | If wrong, the app can't connect to the database and everything breaks. | | `STRIPE_SECRET_KEY` | The secret key that lets the app charge customers. | If wrong, payments fail. If leaked, someone could charge customers fraudulently. | | `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | The public key used on the frontend to identify our Stripe account. | If wrong, the checkout page won't load. | | `JWT_SECRET` | The secret used to sign session tokens. | If wrong, all users get logged out. If leaked, someone could forge login tokens. | | `ADMIN_EMAILS` | A comma-separated list of emails allowed to access the admin dashboard. | If wrong, you might lock yourself out of the admin panel. | **Environments:** - **Development:** Runs on your local machine. Uses a local database (or a separate Supabase project). Changes here don't affect real users. - **Staging:** A production-like environment for testing. Uses a separate Supabase project and Stripe test keys. This is where you test before going live. - **Production:** The real thing. Real database, real Stripe keys, real users. Be careful. **"If you need to change X, you'd update Y - but be careful because Z":** - If you need to change the **database schema**, you'd create a new migration in `supabase/migrations/` and run it. Be careful because migrations are irreversible - once you drop a column, the data is gone. - If you need to change the **Stripe API version**, you'd update the dependency in `package.json`. Be careful because Stripe's API changes can break existing payment flows. - If you need to change the **admin email list**, you'd update the `ADMIN_EMAILS` environment variable. Be careful because if you remove your own email, you'll lose access to the admin panel. **Secrets and keys:** [Describe without revealing values. Example: "We have two Stripe keys (one public, one secret), a JWT secret for session signing, and the Supabase service role key. All of these are stored in environment variables - never in the codebase. The production values are stored in the hosting platform's secret manager. If any secret leaks, rotate it immediately."] --- ## 7. Lessons Learned - The War Stories ### Bugs & Fixes **Bug 1: [Title]** - **What happened:** [Describe the bug in plain language] - **Root cause:** [Explain what caused it, simply] - **How we fixed it:** [Describe the fix] - **How to avoid it:** [Prevention advice] **Bug 2: [Title]** - **What happened:** [Description] - **Root cause:** [Explanation] - **How we fixed it:** [The fix] - **How to avoid it:** [Prevention] ### Pitfalls & Landmines - **[Pitfall 1]:** [Explain what looks simple but is secretly complicated. Example: "Changing the order status flow seems straightforward, but the status field is used in three different places: the customer's order history, the admin dashboard, and the analytics. If you change the status values, you have to update all three or things break silently."] - **[Pitfall 2]:** [Another one] - **[Known technical debt]:** [Be honest. Example: "We never implemented proper error tracking. When something breaks in production, we only find out when a user emails us. We should have added Sentry from day one."] ### Discoveries - **[Discovery 1]:** [What we learned. Example: "We discovered that Supabase's real-time subscriptions are great for small apps but don't scale well past a few hundred concurrent connections. If we grow, we'll need to switch to a dedicated real-time service like Pusher."] - **[Discovery 2]:** [Another one] - **If I were starting over, I would...:** [Honest reflection] ### Engineering Wisdom - **[Wisdom 1]:** [Example: "Always write database migrations as separate files, never edit the schema directly. It's like keeping a journal of every change - you can always go back and see what happened."] - **[Wisdom 2]:** [Example: "Test the payment flow with real money at least once before launch. Test mode doesn't catch everything - we found a bug where refunds worked in test mode but failed in production because of a currency mismatch."] - **[Wisdom 3]:** [Example: "When you're debugging, change one thing at a time. It's tempting to try three fixes at once, but then you don't know which one worked."] --- ## 8. Quick Reference Card **How to run the project locally:** 1. Clone the repository: `git clone [repo-url]` 2. Install dependencies: `npm install` 3. Copy the environment variables: `cp .env.example .env.local` 4. Fill in the environment variables (ask a teammate for the values) 5. Start the development server: `npm run dev` 6. Open `http://localhost:3000` in your browser **Key URLs:** - Production: [URL] - Staging: [URL] - Admin dashboard: [URL]/admin - Database dashboard (Supabase): [URL] **Who to contact when something breaks:** - [Name/Role] - [What they handle] - [Name/Role] - [What they handle] **Most commonly needed commands:** | Command | What It Does | |---------|-------------| | `npm run dev` | Starts the development server | | `npm run build` | Builds the production bundle | | `npm run lint` | Checks for code style issues | | `npm test` | Runs the test suite | | `npx supabase db push` | Applies database migrations | | `npx supabase db reset` | Resets the local database to match migrations |