Repository Structure
Generated projects intentionally separate responsibilities by app to keep code discoverable for humans and AI tools.
High-level layout
apps/core— core business models, shared services, and auth/profile lifecycle logicapps/api— Django Ninja API routers, schemas, API-specific logicapps/pages— landing and product-facing page views/templatesapps/pages/posts/— optional blog Markdown content, handled byapps/pagesapps/pages/content/docs/— optional documentation Markdown content, also handled byapps/pagesapps/mcp_server/— optional generated-app MCP integrationfrontend/— Tailwind, browser modules, vendor assets, and Django templatesdeployment/— container entrypoints and runtime infrastructure files
Why this split matters
For account design, the custom user model and profile guide explains where identity, login policy, and product state belong. Inspect your generated project before choosing the new-database setup or existing-account migration path.
This structure reduces "where should this code go?" ambiguity.
- New domain logic usually belongs in
apps/core. - API endpoints should stay in
apps/apiinstead of being mixed into page views. - Marketing/legal pages stay in
apps/pages. - Presentation assets stay in
frontend/.
That separation keeps reviews cleaner and makes AI-generated patches easier to validate.
URL routing conventions
In <project_slug>/urls.py, app routes are mounted explicitly:
/api/→apps.api.urls- Optional
/blog/and/docs/routes are defined inapps/pages/urls.py, not separateapps.blogorapps.docsapps - app pages/core routes mounted at root
Keep this predictable. New top-level product surfaces should have clear URL namespaces.
Styling conventions
Tailwind is the default styling system. Prefer existing utility patterns before adding custom CSS.
When introducing design changes:
- Reuse the established spacing/typography scale.
- Keep color decisions centralized and consistent.
- Avoid one-off CSS classes unless absolutely necessary.
Practical rule for new features
When adding functionality, ship it as a vertical slice:
- model/service in
apps/core - endpoint in
apps/api(if needed) - page/update in
apps/pages+ templates - background work via Django Q2 task (if asynchronous)
This keeps architecture coherent as the project grows.
Find your first deployment path
The generated docker-compose-prod.yml uses one application image for separate
web and worker services. deployment/Dockerfile builds that image;
deployment/entrypoint.sh selects the process role. These are generated-app
files, not a promise that the hosted Djass deployment runs your app for you.
Use the first production deployment checklist
to prepare the image, HTTPS, email and persistent storage, then verify a real
user workflow. Paths checked against the bundled starter on October 21, 2026.